Skill developer

Purpose

Guide for creating and managing Claude Code skills. Covers skill structure, triggers, rules configuration, and best practices.

When to use

This skill activates when:

• Creating new skills
• Modifying existing skills
• Configuring skill triggers
• Understanding the skill system
• Debugging skill activation

Skill structure

Directory layout

.claude/skills/
├── skill-rules.json          # Skill activation rules
└── my-skill/
    └── SKILL.md              # Skill content

SKILL.md format

---
name: my-skill
description: Brief description for skill activation. Keywords here help trigger the skill.
---

# Skill title

## Purpose

What this skill is for and when to use it.

## When to use

This skill activates when:

- Condition 1
- Condition 2

## Core content

[Skill-specific guidance]

## Checklist

- [ ] Verification item 1
- [ ] Verification item 2

skill-rules.json

Basic structure

{
  "version": "1.0.0",
  "skills": {
    "my-skill": {
      "type": "domain",
      "enforcement": "suggest",
      "priority": "high",
      "description": "What this skill does",
      "promptTriggers": {
        "keywords": ["keyword1", "keyword2"],
        "intentPatterns": ["pattern.*match"]
      }
    }
  }
}

Fields

Prompt triggers

"promptTriggers": {
  "keywords": [
    "exact match word",
    "another keyword"
  ],
  "intentPatterns": [
    "(create|write).*?test",
    "how.*?implement"
  ]
}

File triggers

"fileTriggers": {
  "paths": [
    "**/*.py",
    "**/tests/**",
    "**/pyproject.toml"
  ]
}

Content triggers

"contentTriggers": {
  "patterns": [
    "@dataclass",
    "from typing import",
    "def test_"
  ]
}

Creating a new skill

1. Create directory

mkdir -p .claude/skills/my-skill

2. Create SKILL.md

Write the skill content with frontmatter.

3. Add to skill-rules.json

Add entry with appropriate triggers.

4. Test activation

Try prompts that should trigger the skill.

Best practices

Skill scope

• One skill per domain/concept
• Clear, focused purpose
• Not too broad, not too narrow

Keywords

• Include common terms users would use
• Include technical terms
• Include synonyms

Intent patterns

• Use regex for flexible matching
• Match user intent, not specific phrasing
• Test with various phrasings

Content

• Actionable guidance
• Code examples
• Checklists for verification
• Links to external resources

Example skill

SKILL.md

---
name: api-design
description: API design patterns and best practices for Python APIs.
---

# API design

## Purpose

Guide for designing clean, type-safe Python APIs.

## When to use

This skill activates when:

- Designing public interfaces
- Creating function signatures
- Building class APIs

## Core principles

### Type-safe signatures

\`\`\`python
def process(
    data: list[str],
    *,
    strict: bool = False,
) -> Result:
    ...
\`\`\`

## Checklist

- [ ] All parameters typed
- [ ] Return type specified
- [ ] Keyword-only args for options

skill-rules.json entry

"api-design": {
  "type": "domain",
  "enforcement": "suggest",
  "priority": "high",
  "description": "API design patterns and best practices",
  "promptTriggers": {
    "keywords": ["api design", "function signature", "public interface"],
    "intentPatterns": ["(design|create).*?api", "how.*?signature"]
  },
  "fileTriggers": {
    "paths": ["**/src/**/__init__.py"]
  }
}

Debugging

Check if skill triggers

1. Look for skill activation message in output
2. Verify keywords match your prompt
3. Test intent patterns with regex tester

Common issues

• Keywords too specific (not matching)
• Patterns too broad (matching everything)
• Priority too low (not shown)

Checklist

• SKILL.md has proper frontmatter
• Description includes trigger keywords
• skill-rules.json entry added
• Triggers tested with sample prompts
• Content is actionable and complete

Related files:

• .claude/skills/skill-rules.json - Activation rules
• .claude/hooks/skill_activation_prompt.py - Activation hook