aidb: Skill for Claude Code

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.