So the only way I can see what this skill actually looks like is to download and run it myself? No thank you.
While building https://www.agentkanban.io (a Github CoPilot integrated task board), I experimented a lot with instruction placement. A single degree of separation from AGENTS.md works really well (I needed a robust means of having the agent pick up task specific IDs and so settled on a file called INSTRUCTION.md in a file managed by the tool which avoids polluting AGENTS.md as much as possible). I experimented with skills, but they were skipped too often for the tool to work as reliably as it now does.
1. Less is better. A project rarely needs more than a few skills. A skill is best when the output is measurable and clearly defined. The size of the skill is also very important, since shorter ones are easier to actively maintain and for the agent to reliably follow.
2. Context is important. I keep a short knowledge map in my AGENTS.md file, which gives the agent the context it needs for the overall workflow.
3. Frontmatters work surprisingly well. It pairs nicely with agents and has given me good results (though this might be somewhat of a byproduct).
4. Consistency matters. All skills should follow the same format. For example, I strip all Markdown formatting and enforce a very specific format to them. If you import a skill, do change its format with yours.
I would also go and say not to mistake skills for prompts, but that depends on what you deem the ideal workflow.
I also have an .agents/rules/init.md with the following prompt:
"At the start of every chat or task, you MUST read the following file:
- [AGENTS.md](@AGENTS.md)". Most harnesses find this automatically, and I just give the file to those that don't.
Overall, I’ve found that a project usually only needs the AGENTS.md file and an .agents directory (prompts/, rules/, skills/).
I would love to hear other opinions on the things I just said.
The project in question: https://codeberg.org/hydrafog/kanban (agent-first task manager for the terminal)
e.g.:
/goTailor things to make them your own. First, imagine the kind of workflow you want. Take a pen and a paper and map it out. Second, decide on a format for your agent-related files. Third, offer the prior information to an agent to create a few general iterations. Read them and ask yourself something along the lines of: "Will cutting this affect the workflow?". If not, cut it out.
Instead of jumping and copying the first thing you find, gather knowledge by reading different workflows first. Don't limit yourself to a single field, either. For example, learning about Bloom's Taxonomy can change how you view certain things, so expand your horizons.
Take small steps. It takes a lot of experimentation to reach a good enough workflow.