Yonto Player 倉庫以 Markdown 檔案編寫任何 AI 編碼智能體都能執行的工作流
Our repo's workflows are Markdown files any agent can run
Yonto Player 的程式碼倉庫以 Markdown 檔案編寫工作流,讓 AI 編碼智能體或開發者都能依循同一套流程。倉庫設有七個技能資料夾,每個包含一個 SKILL.md;描述欄界定技能的觸發情境和職責,長流程的補充細節放在 references/。
Yonto Player is a media player for your own library on Android TV, phones and tablets. Its repo keeps its workflows as Markdown files that any AI coding agent, or a person, can follow. This post shows what that means in practice, because the format is small enough to copy.
The repo has a skills/ directory with seven folders. Each holds one file, SKILL.md, and two of them add a references/ folder. There is one for a quality round, one for filing an issue, one for sweeping the issue queue, one for fixing a single issue, one for opening a pull request, one for a walkthrough of the app as a viewer, and one for writing a source plugin.
The shape of a skill
A skill has two parts. At the top is front matter with a name and a description. Below it is the body, which is prose and shell commands in the order you would do them.
Here is a simplified sketch with generic content, not a file from the repo:
---
name: ship-a-change
description: ">"
Use when a change is ready to propose: "open a PR", "put this up",
"/ship-a-change". Produces a PR whose body says why, what and how to test.
---
# Ship a change
One sentence on what a good result looks like.
## Before you write anything
(commands to run, in order, each with the reason it is there)
## The body
(what the three sections hold, and the test of a good one)
## Then
(what comes next, and which other skill covers it)
That is nearly all there is to it. There is no schema beyond those two fields, no code and no registry. A person can read the file top to bottom and follow it, and an agent can be pointed at the same file.
The description is the trigger
The part to get right is the description. The description is what tells an agent when to use the skill.
Most descriptions in this repo start with "Use when" or "Use to", and they share three parts:
- The situation, in the words someone would actually say: "open a PR", "fix an issue", "do a quality round".
- The slash-style name in quotes, so an agent that is told to run a skill by name finds the same file.
- What it covers or produces, so two neighbouring skills do not both claim one job.
The last part matters more than it looks. Filing an issue and fixing an issue are different jobs, and fixing one includes filing it. The fix skill says so in its description, and then points at the filing skill by name instead of repeating its rules. Skills refer to each other by name, which keeps each rule in one place.
No particular agent is assumed
The skills are written so that an assistant with a skill mechanism, one that only reads files, or a person can run them. They do not rely on a particular AI agent product or on a feature only one of them has. The steps use ordinary developer tools: git, gh, a shell and, for work on the app, an emulator.
Where a step needs something an agent may not offer, the skill says what has to happen and what to do if you cannot do it that way. The review step is the clearest example. The fix and sweep workflows end in a review by a fresh worker that had no part in writing the change. The skills say to use a helper where the agent provides one, and otherwise a separate session. The point is the independence of the reviewer, and a helper is only one way to get it.
The skills' README also says where they live. The repo keeps a directory of relative symlinks for assistants that discover skills by a directory convention, so there is one copy of each skill to keep up to date. If another tool expects its own folder, the answer is another symlink.
Steps, in prose and shell
The bodies are written as instructions, not as documentation. Most of the skills put commands in fenced blocks you can copy. The reasoning sits next to them in a sentence.
A few patterns repeat across the seven:
- Order is part of the content. The fix skill is seven numbered steps: reproduce, investigate, plan, file, fix, review, merge. If you cannot reproduce a problem, it says to say so and stop, rather than fix by inference.
- A good result is defined first. The pull request skill opens with a test for a good body: a reviewer who reads it and then reads the diff should find no surprises.
- Evidence is part of the job. The quality round says to take a screenshot after every step and to verify a finding before filing it.
- The queue has an order. The sweep skill says to read the pull request list before the issue list. It ends when the queue is empty, not when the first pass is done.
Supporting material goes under references/
The quality round and the sweep are long, and most of their detail only matters at one step. So the main file stays short and points at a references/ folder.
The quality round keeps two files there: a list of what a round walks, and a set of techniques for reaching states a happy path never visits, such as offline or a stream that never starts. The sweep keeps its rules for several working copies in one coordination.md. They claim an issue in a comment, each picks its own next issue, and none assigns work to another.
An agent that is only fixing a bug usually does not need to read any of that, so it spends no context on it. This is the same idea as the read-this-when table in AGENTS.md, applied to workflows: the entry point is small and says where the depth is.
Docs change with the code
One rule sits above every skill, and the skills' README states it first: a change to the docs, AGENTS.md or a skill happens in the same pull request as the code it describes. The pull request skill has a step for it. It asks what the change makes false, then asks you to search for the subject, not the sentence, and read every hit. Skills describe commands and file paths that have to stay true, so they get the same treatment as code.
What you can take from this
If you want to try it in your own repo:
- Pick a job you repeat, and write the steps as you would explain them to a new teammate.
- Put a
nameand adescriptionin front matter, and write the description as the situation someone would say out loud. - Keep the file short, and move detail that only one step needs into
references/. - Where a step needs a helper, such as a second reviewer, say what to do when you do not have one.
- When one job includes another, point at the other skill by name instead of copying its rules.
Read more
The developer docs describe the plugin contract that the plugin skill points at, and test and debug covers running a plugin without a device. The plugin SDK, command-line tool and public plugins are in the plugins repo. The documentation and the changelog cover the rest.
來源:DEV Community · dev.to