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)