Collection

---
name: skill-developer
description: Create and manage Claude Code skills following Anthropic best practices.
  Use when creating new skills, modifying skill-rules.json, understanding trigger
  patterns, working with hooks, debugging skill activation, or implementing progressive
  disclosure. Covers skill structure, YAML frontmatter, trigger types (AI-powered
  intent analysis, keyword matching), enforcement levels (validation only), hook mechanisms
  (UserPromptSubmit with auto-injection), session tracking, and the 500-line rule.
---

# Skill Developer Guide

## Purpose

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

## When to Use This Skill

Automatically activates when you mention:

- Creating or adding skills
- Modifying skill triggers or rules
- Understanding how skill activation works
- Debugging skill activation issues
- Working with skill-rules.json
- Hook system mechanics
- Claude Code best practices
- Progressive disclosure
- YAML frontmatter
- 500-line rule

## Related Skills

When building skills, reference:

- **testing-strategy** - Skills should be tested with real scenarios before extensive documentation
- **code-reuse-enforcement** - Skills should reference existing patterns/utilities from the codebase

## Relationship to CLAUDE.md

**Division of Responsibilities:**

- **CLAUDE.md**: Global project context, high-level architecture, universal style rules
- **Skills**: Domain-specific detailed guidance, patterns, procedures (triggered by context)
- **skill-developer**: Meta-skill that maintains the skills system and explains its relationship to CLAUDE.md

**When to Update:**

- Global style rules (numpy docstrings, no emojis, use venv) → Update CLAUDE.md
- Domain patterns/practices (test patterns, adapter design) → Update relevant skill
- Skill system mechanics (triggers, hooks, 500-line rule) → Update skill-developer

**Integration:**

- CLAUDE.md references skills for detailed guidance (1-line pointers)
- Skills don't reference CLAUDE.md (avoid circular dependencies)
- skill-developer explains the complete hierarchy (this section)

**Progressive Disclosure Hierarchy:**

```
CLAUDE.md (Global Context)
    ↓ references
Skills (Domain Guidance)
    ↓ maintained by
skill-developer (Meta-Skill)
```

______________________________________________________________________

## System Overview

The skills system uses a **two-tier architecture** (meta-skills vs domain skills) with **automatic injection** to seamlessly provide domain-specific context.

**Key concepts:**

- **Meta-skills** (e.g., skill-developer): Detected via keywords, provided as context awareness (autoInject: false)
- **Domain skills** (e.g., adapter-development, testing-strategy): Automatically injected when detected (autoInject: true)
- **Automatic detection & injection**: Skills detected via AI-powered intent analysis and immediately loaded into context - no manual intervention needed

**For complete details**, see [two-tier-system.md](resources/two-tier-system.md):

- Two-tier enforcement logic
- Automatic skill detection mechanism
- Hook architecture and flow
- Workflow examples and scenarios
- Session state management

______________________________________________________________________

## Skill Types

### 1. Guardrail Skills

**Purpose:** Enforce critical best practices that prevent errors

**Characteristics:**

- Type: `"guardrail"`
- Enforcement: `"block"` (legacy field, no longer blocks with auto-injection)
- Priority: `"critical"` or `"high"`
- Automatically injected when detected (autoInject: true)
- Prevent common mistakes (column names, critical errors)
- Session-aware (only inject once per conversation)

**Examples:**

- `database-verification` - Verify table/column names before Prisma queries
- `frontend-dev-guidelines` - Enforce React/TypeScript patterns

**When to Use:**

- Mistakes that cause runtime errors
- Data integrity concerns
- Critical compatibility issues

### 2. Domain Skills

**Purpose:** Provide comprehensive guidance for specific areas

**Characteristics:**

- Type: `"domain"`
- Enforcement: `"suggest"`
- Priority: `"high"` or `"medium"`
- Advisory, not mandatory
- Topic or domain-specific
- Comprehensive documentation

**Examples:**

- `api-dev-guidelines` - Node.js/Express/TypeScript patterns
- `frontend-dev-guidelines` - React/TypeScript best practices
- `error-tracking` - Sentry integration guidance

**When to Use:**

- Complex systems requiring deep knowledge
- Best practices documentation
- Architectural patterns
- How-to guides

______________________________________________________________________

## Creating New Skills

**5-step process:**

1. Create SKILL.md with YAML frontmatter
1. Add to skill-rules.json with triggers
1. Test detection (UserPromptSubmit hook)
1. Refine patterns based on results
1. Keep under 500 lines with progressive disclosure

**For complete step-by-step guide**, see [skill-creation-guide.md](resources/skill-creation-guide.md):

- File templates and naming conventions
- skill-rules.json configuration
- Trigger testing commands
- Pattern refinement strategies
- Best practices and common mistakes

______________________________________________________________________

## CRITICAL: The 500-Line Rule

**Absolute Limits for ALL Skill Markdown Files:**

- ✅ **Target**: ALL skill files under 500 lines
- ⚠️ **Warning Zone**: Only **5 files maximum** can breach 500 lines across entire skills system (~50 files)
- 🚫 **HARD LIMIT**: **NO file should EVER breach 600 lines**

**Why This Matters:**

- Agents process files linearly - long files waste tokens and context
- 500 lines is the sweet spot for focused, scannable content
- Progressive disclosure (main file → resource files) is more effective than one giant file

**Enforcement Strategy:**

- If approaching 500 lines → **STOP** and extract content to resource files
- If already > 500 lines → Refactor immediately unless you can justify it's in the top 5 most important files
- If approaching 600 lines → **MANDATORY** refactor, no exceptions

**How to Stay Under 500:**

1. Move detailed examples to `resources/` subdirectory
1. Extract deep-dive content to topic-specific resource files
1. Use concise summaries in main SKILL.md, point to resources for details
1. Remove redundancy and wordiness

______________________________________________________________________

## FORBIDDEN: TOCs and Line Number References

**NEVER include in skill markdown files:**

- ❌ **Table of Contents (TOC)** - Bloat for agents, not useful for scanning
- ❌ **Line number references** (e.g., "see line 42") - Change too frequently, create maintenance burden
- ❌ **Heading navigation links** - Agents can scan headings natively

**Why TOCs Are Harmful:**

- Add 10-50 lines of noise
- Agents don't benefit from them (they scan headings natively)
- Become stale when structure changes
- Waste precious lines toward 500-line limit

**Instead:**

- ✅ Use clear, descriptive section headings
- ✅ Use anchor text for cross-references to resource files
- ✅ Keep files under 500 lines so navigation is unnecessary
- ✅ Use progressive disclosure (link to resource files for deep dives)

______________________________________________________________________

## Enforcement Levels

**Note**: With auto-injection, enforcement levels are legacy fields that no longer block execution. All skills with `autoInject: true` are automatically loaded.

- **BLOCK**: (Legacy) Previously prevented tool execution; now just indicates priority for injection
- **SUGGEST**: (Legacy) Previously advisory; now same as BLOCK with auto-injection
- **WARN**: (Legacy) Low priority suggestions; rarely used

Skills are now automatically injected based on detection, regardless of enforcement level. The PreToolUse blocking hook has been removed.

______________________________________________________________________

## Session State & Deduplication

**Automatic session tracking prevents duplicate injection:**

1. **Session tracking**: Skills are injected once per conversation; subsequent detections reuse already-loaded skills
1. **State file**: `.claude/hooks/state/{conversation_id}-skills-suggested.json` tracks loaded skills
1. **Manual loading**: If `autoInject: false` (meta-skills), use `Skill("skill-name")` tool manually

______________________________________________________________________

## Testing & Validation

Test skills manually using the UserPromptSubmit hook:

```bash
echo '{"session_id":"debug","prompt":"your test prompt here"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts
```

For detailed trigger testing strategies, see [trigger-types.md](resources/trigger-types.md).

______________________________________________________________________

## Reference Files

For detailed information on specific topics, see:

### [trigger-types.md](resources/trigger-types.md)

Complete guide to all trigger types:

- Keyword triggers (explicit topic matching)
- Intent patterns (implicit action detection)
- File path triggers (glob patterns)
- Content patterns (regex in files)
- Best practices and examples for each
- Common pitfalls and testing strategies

### [skill-rules-reference.md](resources/skill-rules-reference.md)

Complete skill-rules.json schema:

- Full TypeScript interface definitions
- Field-by-field explanations
- Complete guardrail skill example
- Complete domain skill example
- Validation guide and common errors

### [hook-mechanisms.md](resources/hook-mechanisms.md)

Deep dive into hook internals:

- UserPromptSubmit flow (detailed)
- PreToolUse flow (detailed)
- Exit code behavior table (CRITICAL)
- Session state management
- Performance considerations

### [two-tier-system.md](resources/two-tier-system.md)

Complete two-tier architecture guide:

- Meta-skills vs domain skills
- Automatic skill detection
- Hook flow and enforcement
- Workflow examples
- Session state management

### [skill-creation-guide.md](resources/skill-creation-guide.md)

Step-by-step skill creation:

- File templates and structure
- skill-rules.json configuration
- Trigger testing
- Pattern refinement
- Best practices and common mistakes

______________________________________________________________________

## Quick Reference

**Create New Skill:**

1. Create SKILL.md with frontmatter → 2. Add to skill-rules.json → 3. Test triggers → 4. Refine → 5. Keep < 500 lines

**Critical Rules:**

- ✅ 500-line limit (max 5 files can breach, none > 600)
- ✅ Progressive disclosure (use resource files)
- ✅ NO TOCs or line numbers (forbidden)
- ✅ Test before documenting (3+ scenarios)

**For Details:** See [trigger-types.md](resources/trigger-types.md), [hook-mechanisms.md](resources/hook-mechanisms.md)

______________________________________________________________________

## Self-Healing & Skill Maintenance

### Automated Skill Health Checks

The skills system includes automated maintenance to prevent skill drift:

**1. Pre-commit Hook - Skill Reference Validator**

- **Script**: `scripts/pre-commit/validate_skill_references.py`
- **Runs on**: Changes to skills, internal docs, or src/ files
- **Validates**:
  - All file links in SKILL.md point to existing files (prevents broken refs)
  - New internal docs not yet referenced by skills (suggestions)
- **Exit behavior**: Fails on broken links, warns on missing references

**2. Manual Checklist - /wrap Command**

When wrapping up work, the `/wrap` command includes a skill update checklist:

- New directories/modules → Update skill descriptions to mention them
- New constants/utilities in aidb_common → Update code-reuse-enforcement
- New docs in docs/developer-guide/ → Update skill resource file links
- New patterns/features → Update skill descriptions and promptTriggers keywords

### Skill Update Workflow

**When code changes:**

1. Pre-commit hook catches broken skill references (automatic)
1. Pre-commit hook suggests new patterns to add (informational)
1. `/wrap` command reminds you to check skills (manual)
1. Review `.claude/skills/` for affected skills
1. Update skill-rules.json or SKILL.md as needed

**Common updates:**

- **New module**: Update skill description to mention it for AI intent analysis
- **New utility**: Add reference to code-reuse-enforcement SKILL.md
- **New doc**: Add link to relevant skill's resources section
- **New keyword**: Add to promptTriggers.keywords in skill-rules.json for fallback matching
- **New concept**: Update skill description to help AI understand when to activate the skill

### Best Practices for Skill Health

✅ Run `/wrap` at end of sessions to check for skill updates
✅ Trust pre-commit warnings about unreferenced docs
✅ Keep skill-rules.json in sync with codebase structure
✅ Update skill descriptions when adding new trigger keywords
✅ Test skills after updates to verify triggers still work

______________________________________________________________________

## Related Files

**Configuration:**

- `.claude/skills/skill-rules.json` - Master configuration
- `.claude/hooks/state/` - Session tracking
- `.claude/settings.json` - Hook registration

**Hooks:**

- `.claude/hooks/skill-activation-prompt.ts` - UserPromptSubmit
- `.claude/hooks/error-handling-reminder.ts` - Stop event (gentle reminders)

**All Skills:**

- `.claude/skills/*/SKILL.md` - Skill content files

______________________________________________________________________

**Skill Status**: COMPLETE - Restructured following Anthropic best practices ✅
**Line Count**: < 500 (following 500-line rule) ✅
**Progressive Disclosure**: Reference files for detailed information ✅

**Next**: Create more skills, refine patterns based on usage