6. Writing a Method Down Once as a Skill

Building a Claude Code skill that turns bug reports into a four-part reproduction note before any code changes, including how skills differ from CLAUDE.md and hooks and how to test and fix a skill's description. Also covered: early October Claude Code updates to hooks, debug logging and Sonnet 5.5 cache pricing. This episode is narrated by AI-generated synthetic voices. Episode page & show notes Visit website Skills, CLAUDE.md and hooks The routine for reproducing a bug is a method, and it only matters for certain tasks. CLAUDE.md is read in full every session, so it suits standing rules. A hook is a command Claude Code runs at a set moment whether or not the model remembers. A skill is a method written down once. At startup only its name and short description are read. The model loads the full body with the Skill tool when a request matches. The rule of thumb: a procedure belongs in a skill, and anything a machine must enforce belongs in a hook. Building reproduce-bug A project skill is a folder under .claude/skills/ containing a SKILL.md with frontmatter. The frontmatter needs a name and a description, and the description is the only part the model sees when it decides whether to load the skill (Claude Code skills docs). This skill's description does three things: it names the result, lists the words real bug reports use, and excludes feature requests, refactoring and styling. disable-model-invocation stays off because the skill has no side effects. The body sets out five steps. The agent restates the report as exact steps, records the data, reproduces the bug twice from a clean state, and traces the code read-only. Then it stops with a four-part note: steps, data, observed result and expected result. The body stays well under the guidance of roughly five hundred lines (skill authoring best practices). Testing and fixing the description To test, restart the session and check /skills. Then run a positive test with an emoji bug report, which should load the skill, and a negative test with a sort-button feature request, which should not. A vague description like "Helps with problems in the app" loads the skill on feature work. A narrow one like "Use for reproduction notes" never loads it. Both are fixed by rewording the description, not the body. The disappearing item On the made-up report "Sometimes when I add things fast, one of them disappears," the trace points at a second submit while the first save is still in progress. In the illustrative manual check, the item vanished both times and came back on reload: it was saved, and the screen dropped it. The fix is left for a separate task. The skill gets committed, and CLAUDE.md gains one line pointing to it. Bringing in real issues and logs is left to MCP. Early October Claude Code updates According to the Claude Code changelog, versions 2.1.289–2.1.296 shipped these changes: An onFailure: "block" option for command and HTTP hooks. Hook tracking in debug mode. Sonnet 5.5 cache reads halved to ten cents per million tokens, now reflected in /cost and the status bar. A fix for lost final messages when a session ended. Patches for several shell permission bypasses.