Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

skill-developer

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, keyword triggers, hook mechanisms (UserPromptSubmit), session tracking, and the 500-line rule.

jefflester · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add jefflester/claude-skills-supercharged --skill skill-developer

About this skill


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, keyword triggers, hook mechanisms (UserPromptSubmit), 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.

Domain Skill for Skill System

This is a domain skill for the skills system itself. It's automatically loaded when you work with skills.

This skill covers:

  • The 500-line rule (max 5 files > 500 lines, none > 600 lines)
  • TOC and line number prohibition (never add these to skills)
  • When skills need updates (new dirs, patterns, docs, triggers)
  • Self-healing mechanisms (pre-commit hook, /wrap checklist)
  • Progressive disclosure patterns (main file → resource files)

Use this skill explicitly when:

  • Creating or modifying any skill
  • Debugging skill activation issues
  • Understanding the skills system architecture

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

This skill helps create and manage all other skills. When building skills, reference:

  • testing-strategy - Skills should be tested with real scenarios before extensive documentation

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: Domain skill that guides 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, architecture 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 (Domain Skill)

System Overview

The skills system uses automatic injection to seamlessly provide domain-specific context when you need it.

Key concepts:

  • Domain skills (e.g., python-best-practices, skill-developer): Automatically injected when detected based on prompt keywords and AI intent analysis (autoInject: true)
  • Guardrail skills (e.g., api-security): Enforce critical best practices, automatically injected when detected
  • 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:

  • Skill detection mechanism
  • Automatic skill detection and injection
  • 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"
  • 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"
  • Advisory, not mandatory
  • Topic or domain-specific
  • Comprehensive documentation
  • Automatically injected when detected (autoInject: true)

Examples:

  • backend-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
  2. Add to skill-rules.json with triggers
  3. Test detection (UserPromptSubmit hook)
  4. Refine patterns based on results
  5. Keep under 500 lines with progressive disclosure

For complete step-by-step guide, see 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: **
Read the complete source ↗