Skill Developer

intent

This skill guides you through creating, configuring, testing, and managing skills in Claude Code. Use it when you're building a new skill from scratch, adding trigger rules to skill-rules.json, debugging why a skill isn't activating, understanding the two-hook architecture (UserPromptSubmit and PreToolUse), or learning Anthropic's best practices around the 500-line rule and progressive disclosure. It covers the full lifecycle from conception through testing and deployment.

inputs

Existing skill infrastructure:

• .claude/skills/ directory (skill files live here)
• .claude/skills/skill-rules.json (master config, defines all triggers and enforcement)
• .claude/hooks/skill-activation-prompt.ts (UserPromptSubmit hook, runs before Claude sees prompt)
• .claude/hooks/skill-verification-guard.ts (PreToolUse hook, runs before file edit/write)
• .claude/hooks/error-handling-reminder.ts (Stop hook, runs after response)
• .claude/hooks/state/ directory (session tracking for repeat-nag prevention)
• .claude/settings.json (hook registration)

Reference files (for detailed info, not required input but helpful context):

• TRIGGER_TYPES.md (keyword, intent pattern, file path, content pattern details)
• SKILL_RULES_REFERENCE.md (TypeScript schema, validation, examples)
• HOOK_MECHANISMS.md (flow diagrams, exit codes, performance)
• TROUBLESHOOTING.md (debugging checklist)
• PATTERNS_LIBRARY.md (copy-paste regex and glob patterns)
• ADVANCED.md (future enhancements, versioning ideas)

What you bring:

• Your skill idea (name, purpose, trigger conditions)
• Test scenarios (3+ real prompts to validate triggers)
• Anthropic account or knowledge of their best practices
• Text editor capable of YAML and JSON editing

procedure

1. Decide skill type and enforcement level

   • Input: Your use case (guardrail vs domain guidance)
   • If critical mistake prevention (data integrity, security, runtime errors), choose type "guardrail" with enforcement "block"
   • If advisory guidance (best practices, patterns, how-tos), choose type "domain" with enforcement "suggest"
   • Output: Type and enforcement decided, priority level assigned (critical, high, medium, or low)

2. Create skill file with proper frontmatter

   • Input: Skill name (lowercase, hyphens, gerund form preferred like "processing-pdfs")
   • Create file at .claude/skills/{skill-name}/SKILL.md
   • Add YAML frontmatter: name, description (include all trigger keywords, max 1024 chars)
   • Add these 6 sections: intent, inputs, procedure, decision points, output contract, outcome signal
   • Output: Complete SKILL.md file with valid frontmatter and all sections filled (under 500 lines total)

3. Add skill entry to skill-rules.json

   • Input: Trigger conditions (keywords, intent patterns, file paths, content regex)
   • Open .claude/skills/skill-rules.json
   • Add object with keys: type, enforcement, priority, promptTriggers (keywords + intentPatterns), filePathTriggers (glob), contentPatterns (regex), skipConditions (session/file marker/env var)
   • Validate JSON syntax: jq . skill-rules.json (must exit 0)
   • Output: New skill registered in master config, JSON valid

4. Test UserPromptSubmit trigger (proactive suggestions)

   • Input: Test prompt that should match your keywords/intent patterns
   • Run: echo '{"session_id":"test","prompt":"your test prompt"}' | npx tsx .claude/hooks/skill-activation-prompt.ts
   • Check: Does skill appear in output suggestions?
   • If no: refine keywords (too specific), add intent pattern variations, check JSON syntax
   • If yes but false positives: tighten patterns, add negative lookaheads to regex
   • Output: UserPromptSubmit hook fires correctly for 3+ real test scenarios

5. Test PreToolUse trigger (guardrail blocking, if applicable)

   • Input: File edit that should trigger guardrail (if enforcement is "block")
   • Run: cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts with JSON containing tool_name "Edit" and file_path matching your glob pattern
   • Check: Does hook block with exit code 2 and clear error message?
   • If blocking wrong files: refine glob pattern (e.g., src/**/*.ts vs **/*.ts)
   • If not blocking: check file path pattern, validate regex syntax, confirm enforcement is "block"
   • Output: PreToolUse hook blocks only intended files, allows others, message is actionable

6. Refine patterns based on testing results

   • Input: Test results (false positives, false negatives, edge cases)
   • Add missing keywords discovered during testing
   • Refine intent regex to handle variations ("create", "add", "make", "build")
   • Adjust file path glob to catch new file types
   • Test content patterns against actual file snippets in codebase
   • Iterate: re-run steps 4-5 after each refinement
   • Output: Patterns validated against 3+ real prompts and file scenarios, no false positives in testing

7. Configure skip conditions for repeat-nag prevention (guardrail skills)

   • Input: Session tracking strategy and override mechanism
   • For guardrails: enable session tracking so same file isn't blocked twice per session
   • Add // @skip-validation file marker option for verified files
   • Document emergency disable: export SKIP_SKILL_GUARDRAILS=true or export SKIP_{SKILL_NAME}=true
   • Output: Skip conditions configured, users know how to override if needed

8. Run full testing checklist before deploy

   • Input: Complete skill (SKILL.md + skill-rules.json entry)
   • Verify: file created at correct path, frontmatter valid YAML, all 6 sections present
   • Verify: entry in skill-rules.json with proper structure
   • Verify: keywords tested with 3+ real prompts (no false negatives)
   • Verify: intent patterns tested with variations (no false positives)
   • Verify: file path patterns tested with actual codebase files
   • Verify: content patterns match intended file contents
   • Verify: block message (if guardrail) is clear and actionable
   • Verify: JSON validates, SKILL.md under 500 lines, no em-dashes in prose
   • Output: All checklist items pass, skill ready for production

decision points

• If creating a guardrail skill (enforcement: "block"):

  • Apply critical priority, configure session tracking to prevent nag spam, write an actionable block message that tells user exactly what to do, test on 5+ real file edits, add // @skip-validation file marker option for verified files
  • Else (domain skill, enforcement: "suggest"):
  • Apply high/medium priority, no session tracking needed, write as advisory context, test on real prompts

• If SKILL.md grows over 500 lines:

  • Move detailed examples, schema reference, or step-by-step tutorials to a separate reference file in the same skill directory, add table of contents to reference files over 100 lines, link from main SKILL.md
  • Else:
  • Keep all content in single SKILL.md

• If trigger patterns cause false positives (skill activates too often):

  • Tighten keyword list (remove generic terms), add negative lookaheads to regex, increase intent pattern specificity (e.g., (create|add).*skill instead of just skill)
  • Else if false negatives (skill never triggers):
  • Broaden keywords (plural forms, synonyms), simplify intent regex, check JSON syntax in skill-rules.json

• If hook execution is slow (>200ms):

  • Optimize regex patterns (avoid catastrophic backtracking), reduce content pattern complexity, profile with time command, cache pattern compilation if possible
  • Else:
  • Proceed with current patterns

• If user needs to disable a skill in their session:

  • Use // @skip-validation marker on specific file (permanent), set env var SKIP_{SKILL_NAME}=true (session-only), or set SKIP_SKILL_GUARDRAILS=true (all guardrails off, emergency only)

output contract

• SKILL.md file: Located at .claude/skills/{skill-name}/SKILL.md, valid YAML frontmatter with name and description, 6 sections (intent, inputs, procedure, decision points, output contract, outcome signal), under 500 lines, no em-dashes, lowercase tech-bro prose
• skill-rules.json entry: Valid JSON object with keys type ("guardrail" or "domain"), enforcement ("block", "suggest", or "warn"), priority (critical, high, medium, low), promptTriggers (keywords array, intentPatterns array), optional filePathTriggers (glob array), optional contentPatterns (regex array), optional skipConditions (object with sessionTracking, fileMarkers, envVars)
• Hook test output: UserPromptSubmit outputs formatted reminder with skill suggestion, PreToolUse outputs block message (exit code 2) or passes through (exit code 0)
• Validation: jq . .claude/skills/skill-rules.json exits 0, all test prompts in step 4 trigger correctly, no false positives in 5+ manual tests, block messages (if guardrail) are actionable

outcome signal

• You see your skill name appear in Claude's proactive suggestions when you mention a trigger keyword or act on the skill's intent
• If guardrail: Claude is blocked from editing/writing files until the skill is invoked or skip marker is used; block message appears in stdout
• If domain: Claude sees advisory reminder injected before your prompt; guidance is available without workflow friction
• Session tracking works: same file isn't blocked twice in one session (for guardrails)
• Hook test commands in step 4-5 complete without errors and show expected behavior
• skill-rules.json validates with jq, no JSON syntax errors
• SKILL.md renders cleanly with all sections present and under 500 lines
• Team members can find and use the skill within 30 seconds of searching for its trigger keyword