I'm still finding skill use to be far less reliable than clear instruction in AGENTS.md - I appreciate the idea is to give the agent the opportunity not to add the skill if not relevant to avoid context bloat, but there's no way (without an explicit instruction in AGENTS.md) to ensure that the agent will use the skill, and that point they might as well be any markdown file referenced at any location.
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.
I have a similar project. Through experimentation, I’ve realized a few things about skills that might be useful:
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)
Question for you, since you seem like you know what you're doing here: How do I learn about stuff like agents.md? I feel like every week there's a new Claude feature people are talking about and I have no idea how they learned about it.
Claude auto-injects skill descriptions into the context, and is pretty good about using them. I don’t know about the other harnesses.
I've had cases where it doesn't explicitly use a skill I've added BUT it still performs the actions described in the skill on its own more often than it did before I created the skill. I'd rather it use the skill for consistency, but having it follow most of the steps most of the time in cases I've forgotten to explicitly call out the skill is a better outcome.
in the case of Claude Code, I explicitly kick off skills I want to use by prefixing their name with a `/`
e.g.: