Skill Developer Engine

A comprehensive skill for creating, testing, and managing Claude Code custom skills. Skill Developer Engine guides you through the complete lifecycle — from designing skill prompts with auto-activation patterns to organizing multi-file skill bundles and debugging activation triggers.

When to Use This Skill

Choose Skill Developer Engine when:

• Creating new Claude Code skills with .md files and YAML frontmatter
• Designing auto-activation patterns with glob and regex triggers
• Building multi-step skills that combine multiple tools and workflows
• Debugging why a skill isn't activating or behaving as expected

Consider alternatives when:

• You need to create hooks (event-driven scripts, not skills)
• You're configuring MCP servers (different from skills)
• You want to write Claude Code commands (slash commands, not skills)

Quick Start

Copy
claude "Create a skill that auto-activates when I'm working on Python test files"

Copy
# Skill: Python Test Helper

## File Structure

.claude/skills/ └── python-test-helper.md

## Skill File: `.claude/skills/python-test-helper.md`
```yaml
---
name: python-test-helper
description: Assists with Python testing patterns, fixtures, and assertions
autoActivate:
  files:
    - "tests/**/*.py"
    - "**/test_*.py"
    - "**/*_test.py"
---

# Python Test Helper

When working on Python test files, follow these conventions:

## Test Structure
- Use pytest (not unittest) unless the project already uses unittest
- Group related tests in classes prefixed with `Test`
- Use descriptive test names: `test_should_return_404_when_user_not_found`

## Fixtures
- Define fixtures in `conftest.py` at the appropriate directory level
- Use `@pytest.fixture` with explicit scope (session, module, function)
- Prefer factory fixtures over static data

## Assertions
- Use plain `assert` statements (pytest rewrites them for detailed output)
- Use `pytest.raises` for exception testing
- Use `pytest.approx` for floating point comparisons

Core Concepts

Skill File Anatomy

Section	Purpose	Required
YAML Frontmatter	Metadata, activation rules	Yes
name	Unique identifier	Yes
description	What the skill does (shown in /skills list)	Yes
autoActivate	When the skill auto-triggers	No
Markdown Body	Instructions Claude follows when skill is active	Yes

Auto-Activation Patterns

Copy
# File-based activation
autoActivate:
  files:
    - "src/**/*.tsx"           # Any TSX file in src
    - "*.config.{js,ts}"      # Config files at root
    - "docker-compose*.yml"   # Docker compose files

# Content-based activation (regex)
autoActivate:
  content:
    - "import.*prisma"        # Files importing Prisma
    - "from fastapi"          # Files using FastAPI

# Combined activation (AND logic within a rule)
autoActivate:
  files:
    - "src/api/**/*.ts"
  content:
    - "router\\."

Skill Organization

.claude/skills/
├── code-review.md           # General code review guidance
├── python-test-helper.md    # Python testing conventions
├── api-design.md            # REST API design patterns
├── deploy-checklist.md      # Pre-deployment verification
└── db-migrations.md         # Database migration safety rules

Configuration

Parameter	Description	Default
name	Unique skill identifier (kebab-case)	Required
description	Human-readable skill description	Required
autoActivate.files	Glob patterns for file-based triggering	[]
autoActivate.content	Regex patterns for content-based triggering	[]
alwaysActive	Skill is always loaded into context	false

Best Practices

1. Keep skills focused on one concern. A skill that covers testing, deployment, and code review is doing too much. Split into separate skills with specific activation patterns — this keeps context windows efficient and instructions clear.

2. Use specific glob patterns for auto-activation. Broad patterns like **/* waste context by loading skills unnecessarily. Target exactly the files where the skill's guidance applies: src/api/**/*.ts is better than **/*.ts.

3. Write skill instructions as directives, not explanations. Skills are instructions for Claude, not documentation for humans. Use imperative language: "Use pytest fixtures" not "Pytest fixtures are a feature that allows..."

4. Test activation with edge cases. Create test files matching your glob/regex patterns and verify the skill activates. Check that it doesn't activate on files outside its intended scope — false positives add noise.

5. Version skills with your project. Store .claude/skills/ in version control so the whole team benefits from consistent AI-assisted workflows. Include a brief README explaining what each skill does.

Common Issues

Skill doesn't auto-activate. Check that your glob patterns match the actual file paths (they're relative to the project root). Use claude "/skills" to verify the skill is recognized. Common mistake: using src/**/*.ts when the working directory is already inside src/ — patterns are matched from the project root.

Skill conflicts with other skills. When multiple skills have overlapping activation patterns, all matching skills load simultaneously. If they give contradictory instructions, Claude may produce inconsistent results. Resolve by narrowing patterns or combining overlapping skills into one.

Skill instructions are too long and get truncated. Skills that exceed ~500 lines consume significant context window space. Keep the markdown body under 200 lines by focusing on conventions and rules rather than comprehensive documentation. Link to external docs for reference material.