Develop and Manage Claude Code Skills

Provides a comprehensive guide for creating and managing skills in Claude Code with an auto-activation system, following Anthropic's official best practices including the 500-line rule and progressive disclosure pattern.

Use this skill when creating or adding new skills, modifying skill triggers or rules, understanding how skill activation works, debugging activation issues, working with skill-rules.json, or understanding hook system mechanics. Not a fit for tasks unrelated to Claude Code skill authoring and activation.

Describes a two-hook architecture: a UserPromptSubmit hook (skill-activation-prompt.ts) that runs before Claude sees the user's prompt and injects a formatted reminder suggesting relevant skills based on keyword and intent-pattern matches, and a Stop hook (error-handling-reminder.ts) that runs after Claude responds, analyzing edited files for risky patterns and displaying a gentle, non-blocking reminder rather than blocking the workflow (a deliberate move away from blocking PreToolUse checks). All skill trigger conditions, enforcement levels, file-path glob patterns, content regex patterns, and skip conditions live in .claude/skills/skill-rules.json.

Distinguishes two skill types: guardrail skills (type "guardrail", enforcement "block", used for critical mistakes like verifying database column names before Prisma queries, session-aware so they don't repeatedly nag) and domain skills (type "domain", enforcement "suggest", advisory documentation for complex systems like backend or frontend development guidelines). A five-step quick-start covers creating the SKILL.md file with proper frontmatter, adding an entry to skill-rules.json, testing triggers via npx tsx against the hook scripts, refining keyword/intent/path patterns based on testing, and following Anthropic best practices (under 500 lines, progressive disclosure via reference files, table of contents for files over 100 lines, gerund-form naming).

Documents three enforcement levels (BLOCK: exit code 2, physically prevents Edit/Write until resolved; SUGGEST: advisory context injection; WARN: rarely used, low-priority) and three skip conditions (per-session tracking via state files, permanent // @skip-validation file markers, and emergency environment-variable overrides like SKIP_SKILL_GUARDRAILS). Provides an 16-item testing checklist covering keyword/intent/path/content pattern testing, false positive/negative checks, and the 500-line limit, plus references to detailed guides for trigger types, the skill-rules.json schema, hook mechanics, troubleshooting, and a ready-to-use pattern library.

Built around Claude Code's hook system (.claude/hooks/skill-activation-prompt.ts, .claude/hooks/error-handling-reminder.ts), the .claude/skills/skill-rules.json configuration file, and per-session state tracking under .claude/hooks/state/.

Developers building and maintaining a Claude Code skill library who need concrete guardrail-vs-domain skill design, enforcement-level selection, and activation-pattern testing rather than guessing at how skill triggers and hooks interact.

echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts