From codification
Reference guide to all mechanisms for codifying behaviors, lessons, and guardrails — skills, subagents, hooks, tests, linters, scripts, and more. Trigger phrases: "what mechanism should I use", "how do I codify this", "where should this live", "what are my options for enforcing".
How this skill is triggered — by the user, by Claude, or both
Slash command
/codification:codification-referenceThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A reference guide to the full toolkit of mechanisms for codifying behaviors,
A reference guide to the full toolkit of mechanisms for codifying behaviors, lessons, and guardrails so they are enforced going forward. Covers both Claude-specific mechanisms (skills, subagents, hooks, CLAUDE.md, memories) and general development mechanisms (tests, linters, CI steps, scripts, cron jobs, CLI tools).
Use this when deciding where a lesson, convention, or behavior should live — and how strongly it should be enforced.
These run automatically and catch violations without human attention.
| Mechanism | What it does | Scope | When to use |
|---|---|---|---|
| Test | Asserts an invariant in CI | Per-project | A specific behavior must hold; a regression was found |
| Linter / static analysis | Flags a pattern mechanically | Project or global | A code pattern should always be flagged |
| Pre-commit hook (git) | Blocks commits violating a rule | Per-project | A constraint that should never reach the repo |
| CI step | Enforces a check in the pipeline | Per-project | A property of the built/packaged artifact must hold |
| Script | Automates a deterministic process | Any | A task can be completed without human judgment |
| Cron job | Runs a script on a schedule | System or CI | A check or process needs to run at regular intervals |
These govern agent behavior in relevant sessions. The agent follows instructions rather than mechanical enforcement catching violations.
| Mechanism | What it does | Scope | When to use |
|---|---|---|---|
| CLAUDE.md (project) | Project-specific instructions | Per-project | Conventions, constraints, and context for this codebase |
| CLAUDE.md (global) | Global instructions | All sessions | Behavioral directives that apply everywhere |
| AGENTS.md | Instructions for all AI agents | Per-project | Multi-agent contexts (Cursor, Codex, etc.) |
| Skill (3 modes) | Reusable knowledge or workflow | Global or per-project | See skill modes below |
| Subagent | Scoped agent with specific tools/skills | Global or per-project | A role that should only activate for matching tasks |
| Plugin | Bundled package of skills, hooks, agents | Installable at any scope | Distributing a cohesive set of capabilities |
| Claude hook | Runs on Claude Code events | Global or per-project | "When Claude does X, automatically do Y" |
| MCP server | Exposes external tools to the agent | Global or per-project | Agent needs access to an external system's API |
These inform behavior but don't enforce or direct it.
| Mechanism | What it does | Scope | When to use |
|---|---|---|---|
| Memory (feedback) | Records a correction or validated approach | Per-project or global | A preference that can't be codified as a rule |
| Memory (user) | Records who the user is | Global | Tailoring responses to user expertise/role |
| Memory (project) | Records project context | Per-project | Non-obvious project lore not in code or docs |
| Memory (reference) | Points to external resources | Per-project or global | Bookmarking where to find information |
| Documentation | READMEs, ADRs, inline comments | Per-project | Helping future readers understand non-obvious decisions |
These don't enforce anything but ensure follow-up happens.
| Mechanism | What it does | Scope | When to use |
|---|---|---|---|
| Issue / TODO | Tracks work to be done | Per-project | Needs follow-up but shouldn't block now |
| Template / snippet | A reusable pattern to scaffold | Global or per-project | A pattern worth formalizing for future use |
Skills replaced legacy commands (.claude/commands/) and support three
invocation modes controlled by frontmatter flags:
| Mode | Frontmatter | Who invokes | Use for |
|---|---|---|---|
| Default | (none) | User or Claude auto-triggers | Reference content, workflows Claude should use when relevant |
| User-only | disable-model-invocation: true | User only | Action workflows with side effects you want to control |
| Background | user-invocable: false | Claude only | Context Claude should know but users wouldn't invoke |
Skills can include supporting files (scripts, references, templates) in their directory. Skill descriptions are always in context (~2% of context budget); full content loads on demand when invoked.
→ Deep dive: references/skills-and-subagents.md
→ Official docs: https://code.claude.com/docs/en/skills.md
Three distinct hook systems serve different purposes:
| Hook type | Trigger | Config location | Use for |
|---|---|---|---|
| Claude hooks | Claude Code events (PreToolUse, PostToolUse, etc.) | settings.json | Automating behavior around Claude's actions |
| Git hooks | Git events (pre-commit, pre-push, etc.) | .git/hooks/ or .husky/ | Enforcing code quality before commits/pushes |
| Cursor hooks | Cursor editor events | .cursor/ config | Cursor-specific automation |
Claude hooks and git hooks are complementary — Claude hooks govern agent behavior, git hooks govern repository integrity.
→ Deep dive: references/hooks.md
→ Official docs: https://code.claude.com/docs/en/hooks.md
When automating a capability, choose the right vehicle:
| Vehicle | When to use | When NOT to use |
|---|---|---|
| Script | Deterministic process, no judgment needed | Requires context-dependent decisions |
| Skill | Requires AI judgment, edge case handling | Entirely mechanical — script it instead |
| MCP server | Agent needs live access to an external system's API | A CLI tool already provides the same access |
| CLI tool | Standalone utility usable by humans and agents | Only useful within an agent context |
A skill can (and should) call scripts for its mechanical parts. A CLI tool is often preferable to an MCP server because it works for both humans and agents and doesn't require MCP infrastructure.
→ Deep dive: references/automation.md
→ Official docs (MCP): https://code.claude.com/docs/en/mcp.md
When you have something to codify:
Within each tier, scope as tightly as possible — project over global, specific subagent over always-loaded skill, targeted test over broad documentation.
When a mechanism spans tiers (e.g., a skill that calls a script), use the strongest tier for the mechanical parts and the appropriate tier for the judgment parts.
The Claude Code ecosystem evolves rapidly. When using this reference:
last-reviewed date in frontmatter — if stale, prioritize
verification over recall| Topic | URL |
|---|---|
| Skills | https://code.claude.com/docs/en/skills.md |
| Subagents | https://code.claude.com/docs/en/sub-agents.md |
| Plugins | https://code.claude.com/docs/en/plugins.md |
| Claude hooks | https://code.claude.com/docs/en/hooks.md |
| CLAUDE.md and memory | https://code.claude.com/docs/en/memory.md |
| MCP servers | https://code.claude.com/docs/en/mcp.md |
| Settings and permissions | https://code.claude.com/docs/en/settings.md |
| Commands (legacy) | https://code.claude.com/docs/en/commands.md |
npx claudepluginhub ealt/claude-plugins --plugin codificationGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.