What makes a skill useful

An agent working on a project built on this stack fails in predictable ways. It writes code against the upstream libp2p API it saw in training, not against these packages. It gets two peers talking on loopback and then cannot say why they fail across a NAT. It changes a protocol’s message format in place and breaks deployed peers. It generates a new key on every start. The skills are there to stop those failures.

Skills versus project instructions

	Skills	Project instructions (AGENTS.md, CLAUDE.md, SYSTEM.md)
Loaded	When the task needs one; only the description is always visible	On every turn
Covers	How to use one package: API, recipes, gotchas, tests	This project: which packages, its protocol IDs, where keys live, its commands
Written by	The package maintainers, once, for every project	The project, for itself
Size	A few hundred lines each	As short as possible: it costs tokens on every turn

Anything true of every project that uses a package belongs in its skill. Anything true of one project belongs in that project’s instructions. The AGENTS.md template holds the handful of stack rules worth repeating on every turn: identity, protocol versioning, message caps, closing resources. Those mistakes cost the most and are the easiest to make.

How the set is split

• One entry skill, cryptopeer-stack, maps tasks to packages. Load it first: it tells the agent what exists and which skill to load next.
• One skill per package, or per task where one package has several distinct jobs. dart_libp2p has three: building a host, writing a protocol, and NAT traversal. Each one is loaded alone, so it stays small enough for a local model’s context.
• Cross-cutting skills for work that crosses packages and languages: interop testing, and debugging peers that will not connect.

What goes in a skill

In order of value:

1. Gotchas with fixes. The knowledge an agent cannot get from reading the API: a silent wire break between versions, a call that must come before another, a platform permission. These come from changelogs, fix notes and tests.
2. A minimal working program, with identifiers checked against the source. An agent copies it, so it must compile.
3. Recipes for the common tasks, as short code blocks.
4. How to test code that uses the package without a real network.
5. Red lines: what must never be done.
6. An API map: one line per class or function the agent will need.

Leave out what the agent can read in the source, and the history of how the design came about.

Writing a new skill

Skills live in skills/ in the site repo, one directory per skill holding a SKILL.md. The build (scripts/build-skills.mjs) checks the frontmatter, publishes both layouts and the site page, and adds the skill to the catalogue. Add the skill’s name to GROUPS in that script to place it in the catalogue.

The frontmatter keeps every value on one line, because Boubou reads the header line by line:

---
name: dart-libp2p-host
description: Use when … (says when to load it; names the package, the import and the tasks)
triggers: dart_libp2p, BasicHost, …
---

• name is kebab-case and matches the directory.
• description is all an agent sees before it loads the skill. It says when to use it, not what the package is. Keep it under 400 characters.
• triggers are words that, when they appear in a task, make Boubou load the skill without being asked. Use package and class names, not common words like stream or peer.

Keep the body between 150 and 450 lines, in this order: what it is and when to use something else; install; core workflow; API map; gotchas; testing; red lines; links to the full docs.

When a package changes, update its skill in the same release: a wrong version number or a renamed class in a skill is worse than no skill, because the agent trusts it.