Skills as Software

From Text File to Software Artifact

A SKILL.md file looks like a text document but behaves like a software artifact: it ships, gets stale, accumulates debt, and eventually needs to be retired. Most skill authors treat skills as throwaway prompts. This track treats them as production software — with the engineering practices that implies.

The mental model shift matters because the failure modes are real. A skill whose description has drifted from its actual behavior invokes at the wrong moment. A skill referencing a deprecated API produces wrong output confidently. A skill nobody uses still costs tokens on every session start. None of these failures announce themselves until something has already gone wrong.

The Level 0 Scan: Every Skill Has a Price

At session start, every available skill's name and description loads into context. This is the Level 0 scan — the catalog pass that lets the agent know what tools it has without loading full skill bodies. Full SKILL.md content only loads when a skill is invoked.

An unused skill is therefore not free. Its description costs tokens on every turn until the session ends. When context fills and auto-compaction runs, each invoked skill holds up to 5,000 tokens in a re-attach budget, with all invoked skills sharing a 25,000-token pool. Older skills get dropped entirely when the budget fills. Unused skills that were never invoked still burned description tokens on every turn before that happened.

The /skill-doctor command (Claude Code v2.1.252+) surfaces this directly: it shows token cost per skill, invocation frequency, and flags skills that have never been invoked. The Hermes Curator performs the same function on that platform. Both are the skill equivalent of a dead code detector.

Four Ways Skills Accumulate Technical Debt

• Description drift — the description says what the skill used to do. Claude invokes it at the wrong time, or misses valid invocations entirely.
• Stale procedures — the skill references an API endpoint, file path, or tool that has changed. The instructions remain confident; the output is wrong.
• Token bloat — the skill grew without pruning. Reference material that belongs in references/ lives in SKILL.md and loads on every invocation.
• Undetected non-invocation — no alert fires when a skill is never used. The cost accrues silently while the skill collects dust.

These failure modes apply equally on Claude Code and Hermes. Both platforms use progressive disclosure — description at Level 0, full body on activation — so the economics of unused skills are identical across platforms.

The Five-Stage Skill Lifecycle

Giving skills a lifecycle turns maintenance from a surprise into a routine:

• Experiment — rough draft, used personally, not yet tested in production workflows.
• Validated — used successfully across several real tasks; description accurately reflects behavior.
• Stable — team-accessible, tested, versioned, and owned. Procedures reference current APIs and tools.
• Deprecated — a better skill or approach exists. Description updated to redirect users; skill stays accessible for backward compatibility.
• Retired — removed from skill directories. No longer costs Level 0 scan tokens.

Moving a skill through these stages deliberately — rather than letting it accumulate unnoticed debt — is the core discipline this track teaches. The remaining lessons give you the tools to do it.