skill-creator

What this skill does

# Skill Creator

A meta-skill for generating new Claude Code skills with proper structure and validation.

## When to Use

- Creating project-specific skills (e.g., "Odyssey design system components")
- Building work-related skills (e.g., "SD API client generation")
- Generating custom workflow automations
- Standardizing team practices into reusable skills
- Converting manual processes into automated skills

## Core Workflow

### 1. Gather Requirements

Ask the user:

- **Purpose**: What problem does this skill solve?
- **Triggers**: What keywords/phrases should activate it?
- **Context**: When should it be used (file types, project types)?
- **Location**: Where to save (global or project-local)?
- **Dependencies**: Required tools, packages, or other skills?

### 2. Generate Skill Structure

**Template Reference:** See `templates/skill_template.md` for the complete skill template with all available fields and examples.

Create a properly formatted SKILL.md with:

```yaml
---
# OFFICIAL CLAUDE CODE FIELDS (recognized by Claude Code)
name: skill-identifier                    # Required: kebab-case
description: |                            # Required: What it does AND when to activate
  Clear description of what it does and when to use it.
  IMPORTANT: Include activation triggers in the description itself.
  Example: "Generate React components. Use when creating new UI components."
allowed-tools: []                         # Optional: Restrict to specific tools

# EXTENDED METADATA (ignored by Claude Code, useful for organization)
version: 1.0.0                           # Track changes (skills are files, not packages)
---

# Skill Name

Brief overview (1-2 sentences).

## When to Use

- Concrete trigger 1
- Concrete trigger 2
- Specific scenario 3

## Core Workflow

### 1. First Step
Description and instructions

### 2. Second Step
Description and instructions

## Best Practices

- Practice 1
- Practice 2

## Example Workflows

### Scenario 1: Common Use Case
Step-by-step example

### Scenario 2: Edge Case
How to handle edge cases

## Integration Points

- Works with: [other skills]
- Calls: [agents/tools]
- Required by: [dependent skills]

## Troubleshooting

### Issue 1
Symptom: [description]
Solution: [fix]

### Issue 2
Symptom: [description]
Solution: [fix]

## References

- [External documentation links]
```

### 3. Validate Against Specifications

Ensure the skill follows:

**Anthropic Best Practices:**

- ✅ Clear, actionable instructions
- ✅ Specific triggers (not generic)
- ✅ Real examples (not placeholders)
- ✅ Token-efficient (< 500 lines for core content)
- ✅ Progressive disclosure (link to API_REFERENCE.md if needed)

**RED-GREEN-REFACTOR Ready:**

- ✅ Can be tested without the skill (RED phase)
- ✅ Verifiable compliance (GREEN phase)
- ✅ Hardened against rationalizations (REFACTOR phase)

**Community Patterns:**

- ✅ No TODOs or placeholders in production
- ✅ No "YOUR_KEY_HERE" style configs
- ✅ Specific, not generic labels
- ✅ Context-aware activation

### 4. Save to Appropriate Location

**Global Skills** (general use across all projects):

```txt
~/.claude/skills/super-claude/plugins/[category]/skills/skill-name.md
```

**Project-Local Skills** (specific to one project):

```txt
/path/to/project/.claude/skills/skill-name.md
```

**Note**: Project-local skills are perfect for work-specific or proprietary patterns that shouldn't be shared globally.

### 5. Test the Skill

Provide testing guidance:

- RED: Try the workflow WITHOUT the skill, note failures
- GREEN: Enable the skill, verify it works
- REFACTOR: Identify edge cases, harden the skill

## Skill Types

### Standard Skill (Most Common)

General-purpose automation or guidance for specific tasks.

### Component Generator

Creates code/files following specific patterns.

### Workflow Orchestrator

Coordinates multiple steps or tools.

### Validation/Checker

Ensures code/config meets standards.

### Migration Helper

Assists in moving between technologies.

## Advanced Features

### Progressive Disclosure

If skill exceeds 500 lines, split into:

- **SKILL.md**: Core instructions (< 500 lines)
- **API_REFERENCE.md**: Advanced topics (loaded on-demand)

Link from SKILL.md:

```markdown
For advanced usage, see [API_REFERENCE.md](./API_REFERENCE.md)
```

### Context-Aware Activation

Make skills activate automatically:

```yaml
triggers:
  keywords: [specific, technical, terms]
  patterns: ['regex.*patterns']
  contexts: [file-types, project-types]
```

### Dependencies

Declare requirements:

```yaml
requires:
  tools: [git, npm, docker]
  skills: [typescript/tsc-validation]
  packages: ['@types/node']
```

## Auto-Activation System

### Overview

Skills can auto-activate based on user prompts using the skill-rules.json system. This enables Claude to proactively suggest relevant skills before responding.

**For complete details, see:** [SKILL_ACTIVATION_GUIDE.md](../../docs/SKILL_ACTIVATION_GUIDE.md)

### When to Add Activation Rules

Add skill-rules.json entries when:

- Skill is part of a plugin (not project-local)
- Skill should auto-activate from specific keywords
- Skill addresses a common workflow pattern
- Skill is high-value and frequently needed

**Skip activation rules for:**

- One-off project-specific skills
- Rarely-used experimental skills
- Skills that should only run on explicit user request

### Creating skill-rules.json Entries

**For plugin developers:** Add entries to `plugins/{plugin}/skills/skill-rules.json`

**Schema:**

```json
{
  "plugin": {
    "name": "plugin-name",
    "version": "1.0.0",
    "namespace": "namespace"
  },
  "skills": {
    "skill-name": {
      "type": "domain",
      "enforcement": "suggest",
      "priority": "high",
      "description": "Brief description of what the skill does",
      "promptTriggers": {
        "keywords": ["keyword1", "keyword2"],
        "intentPatterns": ["pattern1", "pattern2"]
      }
    }
  }
}
```

### Writing Good Keywords

**✅ Good Keywords** (specific, unambiguous):

```json
"keywords": [
  "create skill",
  "new skill",
  "skill template",
  "generate skill",
  "skill development"
]
```

**❌ Bad Keywords** (too generic):

```json
"keywords": [
  "create",
  "new",
  "help",
  "build"
]
```

**Rules for keywords:**

- Minimum 2 words for specificity
- Include the domain (e.g., "skill", "hook", "component")
- Match how users naturally ask for help
- Case-insensitive literal matching
- No regex needed for keywords

### Writing Good Intent Patterns

**✅ Good Patterns** (capture intent, not exact wording):

```json
"intentPatterns": [
  "(create|add|generate|build).*?skill",
  "how to.*?(create|add|build).*?skill",
  "skill.*?(template|generator|builder)",
  "need.*?skill.*?(for|to)",
  "(make|write).*?skill"
]
```

**❌ Bad Patterns** (too broad or too narrow):

```json
"intentPatterns": [
  ".*skill.*",
  "^create exactly this specific phrase$"
]
```

**Rules for patterns:**

- Use regex with case-insensitive flag (`i`)
- Include action verbs: create, add, generate, build, make
- Include domain terms: skill, hook, component, etc.
- Use `.*?` for flexible matching between keywords
- Capture natural variations of the same intent

### Priority Guidelines

**critical** - Must run for safety/correctness:

```json
"priority": "critical"
// Examples: security validators, syntax checkers
```

**high** - Highly recommended:

```json
"priority": "high"
// Examples: skill-creator, component-generator
```

**medium** - Useful but optional:

```json
"priority": "medium"
// Examples: documentation generators, formatters
```

**low** - Nice-to-have:

```json
"priority": "low"
// Examples: experimental features, rarely-used tools
```

### Example: skill-creator Activation Rules

```json
{
  "plugin": {
    "name": "meta",
    "version": "1.0.0",
    "namespace": "claude"
  },
  "skills": {
    "skill-creator": {
      "type": "domain",
      "enforcement": "suggest",
      "priority": "high",
      "description": "Generat