---
name: skill-creator
version: 1.0.0
description: |
  Create new Claude Code skills with proper structure, validation, and best practices.
  Generates skills that follow Anthropic specifications and community patterns.
  Use when you need custom skills for specific workflows, either globally or per-project.
category: meta
tags: [skill-generation, meta, automation, claude-code]
model: sonnet
triggers:
  keywords: [create skill, generate skill, new skill, custom skill, skill for]
  patterns: ['create.*skill', 'generate.*skill', 'make.*skill']
  contexts: [development, skill-creation]
---

# 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": "Generate new Claude Code skills with proper structure and validation",
      "promptTriggers": {
        "keywords": [
          "create skill",
          "new skill",
          "skill development",
          "generate skill",
          "skill template"
        ],
        "intentPatterns": [
          "(create|add|generate|build).*?skill",
          "how to.*?(create|add|build).*?skill",
          "skill.*?(template|generator|builder)",
          "need.*?skill.*?(for|to)",
          "(make|write).*?skill"
        ]
      }
    }
  }
}
```

### Migration Tool

Use `/generate-skill-rules` to auto-generate entries from existing SKILL.md YAML frontmatter:

```sh
# Preview generated rules
/generate-skill-rules --plugin plugins/tanstack-tools --namespace tanstack

# Write to skill-rules.json
/generate-skill-rules --plugin plugins/api-tools --namespace api --write
```

### Testing Activation Rules

**Test in isolated project:**

```sh
# 1. Create test project
mkdir test-activation && cd test-activation

# 2. Copy hook and rules
mkdir -p .claude/hooks .claude/skills/your-plugin
cp {hook-path}/skill-activation-prompt.ts .claude/hooks/
cp {plugin-path}/skill-rules.json .claude/skills/your-plugin/

# 3. Test with prompts
echo '{"prompt":"create a new skill","cwd":"'$(pwd)'"}' | \
  bun run .claude/hooks/skill-activation-prompt.ts
```

**Expected output:**

```txt
============================================================
SKILL ACTIVATION CHECK
============================================================

[RECOMMENDED] SKILLS:
  -> skill-creator

ACTION: Use Skill tool BEFORE responding
============================================================
```

### Workflow: Adding Auto-Activation to New Skills

When creating a skill that should auto-activate:

1. **Create the SKILL.md** (as normal)

2. **Identify triggers** by asking:
   - What keywords would users type to need this skill?
   - What questions or requests indicate this intent?
   - How do users naturally express this need?

3. **Add to skill-rules.json**:

   ```json
   {
     "skills": {
       "new-skill": {
         "type": "domain",
         "enforcement": "suggest",
         "priority": "high",
         "description": "What the skill does",
         "promptTriggers": {
           "keywords": ["keyword1", "keyword2"],
           "intentPatterns": ["pattern1", "pattern2"]
         }
       }
     }
   }
   ```

4. **Test the triggers**:
   - Try prompts that SHOULD activate it
   - Try prompts that should NOT activate it
   - Refine keywords/patterns based on results

5. **Document in SKILL.md**:

   ```markdown
   ## Auto-Activation

   This skill auto-activates when you mention:

   - Creating/generating {domain objects}
   - Specific workflow requests
   - Related keywords

   Triggered by: create skill, new skill, generate skill
   ```

### Project-Level Overrides

Users can customize activation in their projects via `.claude/skills/skill-rules.json`:

```json
{
  "version": "1.0",
  "overrides": {
    "claude/skill-creator": {
      "priority": "critical"
    }
  },
  "disabled": ["claude/skill-validator"],
  "global": {
    "maxSkillsPerPrompt": 3,
    "priorityThreshold": "medium"
  }
}
```

**Command for users:** `/workflow:configure`

## Example: Creating a Project-Specific Skill

**User Request:**
"Create a skill for generating Odyssey design system components"

**Generated Skill:**

Location: `/path/to/odyssey-project/.claude/skills/odyssey-components.md`

```yaml
---
name: odyssey-components
version: 1.0.0
description: |
  Generate components following Odyssey design system guidelines.
  Ensures consistency with design tokens, patterns, and accessibility standards.
category: design-system
tags: [odyssey, components, design-system, react]
model: sonnet
requires:
  tools: [npm]
  packages: ["@odyssey/design-tokens", "@odyssey/components"]
triggers:
  keywords: [odyssey, odyssey component, design system]
  patterns: ["create.*odyssey", "generate.*odyssey"]
---

# Odyssey Components

Generate React components that follow Odyssey design system standards.

## When to Use

- Creating new Odyssey components
- Ensuring design system compliance
- Maintaining consistency across products

## Component Structure

All components follow this pattern:

\`\`\`
components/
  └── ComponentName/
      ├── ComponentName.tsx
      ├── ComponentName.stories.tsx
      ├── ComponentName.test.tsx
      └── index.ts
\`\`\`

## Design Token Usage

Always use design tokens from `@odyssey/design-tokens`:

\`\`\`typescript
import { tokens } from '@odyssey/design-tokens'

const styles = {
  color: tokens.color.primary.base,
  spacing: tokens.spacing.md,
  borderRadius: tokens.borderRadius.md
}
\`\`\`

## Accessibility Requirements

All components must:
- Meet WCAG AAA standards
- Include proper ARIA labels
- Support keyboard navigation
- Provide focus indicators

## Example: Button Component

[Detailed example following Odyssey patterns]
```

## Common Skill Patterns

### API Client Generator

```yaml
name: project-api-client
purpose: Generate type-safe API clients from OpenAPI schemas
includes: OpenAPI schema parsing, type generation, RPC helpers
location: project-local (for proprietary APIs)
```

### Component Library Helper

```yaml
name: design-system-components
purpose: Generate components following project design system
includes: Component patterns, theme support, testing
location: project-local (for proprietary design systems)
```

### Database Schema Generator

```yaml
name: drizzle-schema-from-db
purpose: Generate Drizzle schemas from existing Postgres database
includes: Type inference, relationship mapping, migration helpers
location: global (reusable across projects)
```

### Deployment Automation

```yaml
name: coolify-deployment
purpose: Automate deployment to Coolify platform
includes: Docker config, environment setup, rollback procedures
location: global (reusable deployment pattern)
```

## Best Practices

1. **Be Specific**: Don't create "helper" or "utility" skills - be explicit about what they do
2. **Include Examples**: Real, working examples - not placeholders
3. **Test First**: RED-GREEN-REFACTOR methodology ensures quality
4. **Token Efficiency**: Keep core content under 500 lines
5. **Clear Triggers**: Specific keywords that clearly indicate when to activate
6. **Validate**: Always check against Claude Code and Anthropic specs

## Anti-Patterns to Avoid

- ❌ Generic names ("helper", "utils", "tool")
- ❌ TODOs or placeholders in production
- ❌ Narrative examples tied to specific sessions
- ❌ Code embedded in flowcharts
- ❌ Missing activation triggers
- ❌ Over 500 lines without progressive disclosure
- ❌ Untested skills

## Integration with Other Tools

### shadcn CLI Integration

```bash
# Generate skill that wraps shadcn commands
pnpm dlx shadcn@latest add [component]
pnpm dlx shadcn@latest add @coss/[component]
```

### Registry Support

Skills can integrate with component registries:

- shadcn/ui registry
- coss.com/ui registry
- Custom private registries

## Troubleshooting

### Skill Not Activating

**Symptom**: Skill exists but doesn't trigger
**Solution**:

- Check triggers section in YAML frontmatter
- Ensure keywords are specific enough
- Verify file is in correct location
- Check Claude Code loaded the skill (restart if needed)

### Skill Too Generic

**Symptom**: Skill triggers too often or in wrong contexts
**Solution**:

- Make keywords more specific
- Add context restrictions
- Use regex patterns to narrow activation

### Skill Too Large

**Symptom**: Skill exceeds 500 lines
**Solution**:

- Implement progressive disclosure
- Move advanced content to API_REFERENCE.md
- Keep core workflow in SKILL.md

## References

- [Claude Code Skills Documentation](https://docs.claude.com/en/docs/claude-code/skills)
- [Anthropic Best Practices](https://docs.claude.com/en/docs/claude-code)
- [obra/superpowers](https://github.com/obra/superpowers) - Community patterns
- [super-claude CREATING_SKILLS.md](../../docs/CREATING_SKILLS.md) - RED-GREEN-REFACTOR guide