| name | skill-management |
| description | Self-documentation for Claude Code. MUST READ after implementing complex features, making structural changes, or learning non-obvious patterns that would be useful in future sessions. Covers: when to create or update .agents/skills/ files, what belongs in a skill vs CLAUDE.md vs auto-memory, the skill file format, and the maintenance checklist to run before finishing work. |
Self-Documentation
You (Claude Code) are the primary consumer of .agents/skills/. These files are your
persistent knowledge base for working on this codebase. They survive across sessions and
make you effective from the first turn.
Core principle: whenever you learn something useful that doesn't belong in
CLAUDE.md, capture it in a skill so your future self doesn't have to rediscover it.
When to Create or Update a Skill
After implementing a complex feature
If the feature has conventions, multi-file coordination, or non-obvious rules — write
them down. Examples of things that warranted a skill:
- Testing harness (
/testing) — helpers, mock types, readability rules
- Tracing (
/tracing) — span naming, OTel conventions, #[instrument] patterns
- Lua scripting (
/lua-scripting) — host globals, ctx bindings, sandbox rules
- E2e tests (
/e2e-testing) — fixture layout, step chaining, iteration workflow
After making structural changes
If you moved files, renamed types, changed module boundaries, or altered a subsystem's
public API — check if an existing skill references the old names and update it.
After debugging a non-obvious issue
If you spent significant effort diagnosing something (e.g., "reqwest 0.13 renamed
rustls-tls to rustls"), that's worth capturing. Future sessions shouldn't repeat the
investigation.
After discovering a pattern the codebase relies on
If you notice the codebase consistently follows a convention that isn't documented
anywhere (e.g., "all provider errors use retry-after headers"), write it down.
What Goes Where
| Content | Destination | Why |
|---|
| Project-wide rules everyone must follow | CLAUDE.md | Always loaded, high visibility |
| Subsystem-specific conventions & API reference | .agents/skills/<name>/SKILL.md | Loaded on demand via /skill-name |
| Session-specific context, task state | Auto-memory (memory/MEMORY.md) | Lightweight, auto-managed |
| Operator-facing workflows for the GHOST | prompts/skills/<name>.md | Embedded in binary, for runtime |
Rule of thumb: if the information is needed every session, it goes in CLAUDE.md.
If it's needed when working on a specific subsystem, it goes in a skill. If it's
ephemeral or speculative, it goes in auto-memory (or nowhere).
Skill File Format
Developer skills live in .agents/skills/<name>/SKILL.md:
---
name: skill-name
description: >-
One paragraph. Start with what it covers. Then say WHEN to read it (triggers). The
description is shown in the skill list — make it specific enough that you know when to
load the full file. Under 1024 chars.
---
# Title
## Section — concrete rules, tables, code examples
Description triggers
The description field is what you see in the skill list. Write it so you'll know to
load the skill at the right time. Good triggers:
- "MUST READ before modifying anything in src/scripting/"
- "MUST READ before writing or modifying any test"
- "MUST READ after implementing complex features or making structural changes"
Content guidelines
- File paths — which files to read/modify for this subsystem
- Contracts — data formats, type shapes, naming conventions
- Do/Don't rules — concrete, actionable, with rationale
- Patterns — recurring code shapes with short examples
- Gotchas — non-obvious behaviors, known failure modes, migration notes
- Keep skills under 500 lines. Split if needed (
testing + e2e-testing).
- Use lowercase kebab-case names:
lua-scripting, e2e-testing
Runtime Skills (for the GHOST, not for you)
The GHOST runtime also has skills in prompts/skills/. These teach the GHOST how to
perform operator tasks. Some are symlinked into .agents/skills/ so you can read them
too (e.g., agent-creator).
| Directory | Audience | Loaded by |
|---|
prompts/skills/ | GHOST runtime | Embedded in binary, installed to $WORKSPACE/skills/ |
.agents/skills/ | Claude Code (you) | Read via /skill-name in sessions |
When modifying a runtime skill, remember it gets compiled into the binary via
include_str!() in src/skills.rs.
Maintenance Checklist
Run this mentally before finishing any significant PR:
- Did I change a subsystem that has a skill? Grep:
rg "file_or_type_I_changed" .agents/skills/. Update any stale references.
- Did I learn something non-obvious? If yes, does it belong in an existing skill or
a new one?
- Are the description triggers still accurate? Would you find the right skill when
working on this feature next time?
- Remove stale content — delete sections about removed features, don't comment them
out.
