Writing one skill is easy.
Organizing ten
is where agents break.
A methodology to organize agent skills as a coherent system. Resolve skill trigger conflicts, decide when to build a new skill, and stop the failures that no single skill can explain.
More skills made your agent worse, not better.
Not edge cases. The documented failure mode of any skill collection that grows without a system behind it. If you have shipped a few skills, you have met at least one of these.
Two skills both fire on the same request. The agent silently picks the wrong one and you cannot tell why.
Duplicate skills loading on every turn, wasting your context window before the agent has done anything useful.
Adding more skills degraded accuracy. The new one shadowed an existing one instead of helping it.
You edit one skill and something completely unrelated breaks elsewhere. No isolation between skills.
These symptoms recur across Cursor and Claude Code communities. Skill shadowing, where adding skills degrades performance, is a measured effect in agent-skills research. The bug is never in one skill. It is in the system.
Writing one skill is a craft. Architecting fifty is engineering.
Every guide on the planet teaches the first half. Nobody teaches the second. That gap is where agents quietly break.
Existing guides
How to write a single skill well. Progressive disclosure, description fields, degrees of freedom. Necessary, but it is teaching you to write one good function.
System of Skills
How to architect the whole collection. When skills conflict, when to merge instead of build, how to verify the system holds. The systems-engineering layer that was missing.
| Codebase concept | What it becomes in a skill system |
|---|---|
| modulea unit of code with one job | skilla unit of agent behavior with one trigger |
| interfacehow callers address the module | triggerthe observable yes/no condition that loads the skill |
| contractwhat the module promises to return | output shapewhat the skill leaves behind for the next skill or turn |
| kernel / core libshared primitives every module relies on | core promptthe stable principles every skill traces back to |
| regression testdoes this piece still work after a change | eval loopdoes the whole collection still trigger cleanly and run end-to-end |
A skill collection is a codebase. Treat it like one.
Seven principles to keep a skill collection coherent.
Each one solves a specific failure mode of an unmanaged collection. Together they form a system you can actually reason about.
Persistence Gradient
Decide what stays loaded across turns versus what loads per task. Stops context bloat from duplicate skills.
System Coherence
Skills must agree on shared state, naming, and authority. The collection behaves as one agent, not a committee.
Regime Gating
Only one skill owns a request at a time. The first line of defense against trigger conflicts.
Orthogonal Coverage
Two skills should not overlap in scope. Forces the merge-or-split decision before you build.
Flow
Skills hand off cleanly along the real task path. No dead ends, no circular delegation between subagents.
Granularity
Right-size each skill. Kill god-skills that try to handle everything and whose trigger means nothing.
Self-Contained Verification
Every skill ships an executable self-check — script, fixture, or output invariant. Prose self-assessment doesn't count; a check that can't run can't block a silent failure.
Single-skill eval asks "does this piece work?" System-level eval asks "do all pieces together cover the space, trigger unambiguously, survive changes, and run end-to-end?" Baseline without the skill first. No reproducible failure, no justification to build it.
Apply it from inside your agent.
One command. Then your agent applies these principles the moment you ask "should I build a new skill?" or "why is my agent behaving unpredictably?". Works in Claude Code, Cursor, and any agent that reads ~/.claude/skills/.
$ cp -r skill/ ~/.claude/skills/system-of-skills/ # ask your agent: > should I build a new skill, or merge into an existing one? ✓ system-of-skills loaded · 7 principles active
No build step, no dependencies. The skill itself is plain Markdown.