codify

Codify

Overview

A structured workflow for taking a lesson, behavior, convention, or guardrail and codifying it into the strongest, most appropriately scoped mechanism available. This is the action counterpart to the codification-reference skill — use that for browsing options, use this when you have something specific to codify.

Arguments

$ARGUMENTS — a description of what needs to be codified. Can be a lesson learned, a behavior to enforce, a process to automate, or a convention to establish.

Workflow

Step 1: Understand What's Being Codified

Before choosing a mechanism, fully understand the input:

• What is it? A lesson, a convention, a process, a guardrail, a behavior?
• Why does it matter? What goes wrong if it's not codified?
• How broadly does it apply? One project, all projects, one ecosystem, one team?
• How deterministic is it? Fully mechanical, requires judgment, or a mix?

Ask clarifying questions if the input is ambiguous. Don't proceed until the scope is clear.

Step 2: Select the Mechanism

Load the codification-reference skill for the full mechanism taxonomy. Then apply the decision process:

1. Can it be caught mechanically? → Test, linter rule, CI step, hook, script
2. Is it a behavioral directive? → CLAUDE.md, subagent, skill, or plugin
3. Is it context that informs judgment? → Memory or documentation
4. Does it need follow-up work? → Issue or TODO

Selection principles:

• Prefer the strongest mechanism that fits
• Script what's mechanical, even within judgment-heavy workflows
• Scope as tightly as possible
• If the right mechanism isn't obvious, discuss the tradeoffs — present options with pros/cons rather than making an assumption

Present the proposed mechanism to the user with:

• What mechanism and why
• What scope (project, global, etc.)
• What the tradeoffs are vs alternatives considered
• Get confirmation before proceeding

Step 3: Implement

Build the chosen mechanism:

• Test: Write the test, verify it catches the case
• Linter rule: Configure the rule, verify it flags the pattern
• Hook: Add to settings.json, test the trigger
• Script: Write the script, make it executable, test it
• Skill: Create the skill directory, write SKILL.md, add supporting files. Quote frontmatter values containing colons or brackets (strict YAML parsers break otherwise). Use skills/_template/ as starting point.
• Subagent: Write the agent definition, configure tools/skills
• CLAUDE.md: Add the directive to the appropriate file
• Memory: Write the memory file, update MEMORY.md
• Issue: File in the appropriate tracker
• CI step: Add to the pipeline config

Show the user what you're writing and get confirmation before each write.

Step 4: Verify

After implementation:

1. Test the mechanism — does it actually catch/enforce/automate what it should?
2. Check the scope — is it installed/configured at the right level?
3. Check for conflicts — does it contradict or duplicate existing mechanisms?
4. Summarize — what was codified, where it lives, and what it does

Best Practices

1. Don't default to memory. Memory is the weakest mechanism — only use it when nothing stronger fits.
2. Don't mix concerns. One mechanism per concern. If a lesson has both a mechanical part and a judgment part, use separate mechanisms for each.
3. Check for existing mechanisms first. Read MEMORY.md, CLAUDE.md, and relevant config before creating something new — the lesson may already be partially codified.
4. Write for the future reader. Whether it's a test name, a CLAUDE.md directive, or a skill description — make the intent clear to someone without today's context.