Skip to content

Creating Skills

This guide covers creating Claude Code skills from scratch or from external sources.

Pre-Build Requirements

CRITICAL: Do not skip this section. Skills without proper requirements and examples rarely meet quality standards.

Full requirements checklist: See Requirements Stack for the complete list of 7 required input categories and where they live in the repo.

Before writing any code, ensure you have:

1. User Stories Documented

Check references/by-division/{division}/review-booklet.md for:

  • WHO uses this capability
  • WHAT they need to produce
  • WHY it matters to the business

2. Golden Examples Collected

Gather 2-3 examples from references/by-division/{division}/examples/:

  • Best-in-class deliverables
  • Consistent patterns to encode
  • Common mistakes to prevent

3. Quality Criteria Defined

Document how success will be measured:

  • What makes output "correct"?
  • What validation can be automated?
  • What requires human review?

Don't Skip This

Skills built without user stories and golden examples often miss the mark. The 30 minutes spent on prerequisites saves hours of rework.

Choose Your Approach

Approach Best For Time
Manual authoring Custom skills, guardrails, complex triggers 30-60 min
skill-seekers CLI Importing docs, GitHub repos, or PDFs 20-40 min
Combined Generate base, customize triggers 40-60 min

Manual Skill Authoring

Step 1: Create Directory Structure

mkdir -p skills/my-skill/resources

Last updated: 2026-01-26

Step 2: Create SKILL.md

---
name: my-skill
description: "What it does and when to use. Include trigger keywords."
type: skill
version: 1.0.0
---

# My Skill

## Purpose
What this skill helps with

## When to Use
Specific scenarios

## Key Information
Guidance, patterns, examples

Rules:

  • Keep under 500 lines
  • Use third person ("This skill..." not "I help...")
  • Include trigger keywords in description
  • Put detailed content in resources/

Claude.ai Team Skills Compliance

For skills distributed via Claude.ai Admin:

  • name: Max 64 characters, lowercase + hyphens only
  • description: Max 200 characters (Claude.ai limit, stricter than general 1024)
  • Write in third person ("Applies..." not "I help...")

Step 3: Add Activation Triggers

Create skill-rules-fragment.json:

{
  "my-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "high",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(create|add).*?something"]
    },
    "fileTriggers": {
      "pathPatterns": ["**/relevant-path/**"]
    }
  }
}

Step 4: Test Activation

echo '{"session_id":"test","prompt":"your test prompt"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

Automated Generation with skill-seekers

Installation

pip install skill-seekers

From GitHub Repository

# Scrape repo
skill-seekers github --repo facebook/react --name react-docs

# AI enhancement
skill-seekers enhance output/react-docs/ --ai-mode local

# Package
skill-seekers package output/react-docs/

From Documentation Website

skill-seekers scrape --url https://docs.acme.com --name mylib
skill-seekers enhance output/mylib/
skill-seekers package output/mylib/

From PDF

skill-seekers pdf --pdf docs/manual.pdf --name myskill
skill-seekers enhance output/myskill/
skill-seekers package output/myskill/

One-Command Pipeline

# Full automation: scrape → enhance → package → upload
skill-seekers install --config react

# Without upload
skill-seekers install --config django --no-upload

Add Triggers Manually

skill-seekers generates content but not activation triggers. After generation, create skill-rules-fragment.json manually.

Skill Types

Domain Skills (Advisory)

Suggest guidance without blocking.

{
  "type": "domain",
  "enforcement": "suggest",
  "priority": "high"
}

Use for: Best practices, methodologies, how-to guides

Guardrail Skills (Blocking)

Block file edits until skill is used.

{
  "type": "guardrail",
  "enforcement": "block",
  "priority": "critical",
  "blockMessage": "BLOCKED - Use skill 'my-skill' first\n\nFile: {file_path}"
}

Use for: Database operations, security checks, data integrity

Trigger Types

Keyword Triggers

Case-insensitive substring matching:

"keywords": ["prisma", "database", "schema"]

Intent Pattern Triggers

Regex patterns for user intent:

"intentPatterns": [
  "(create|add).*?(database|table)",
  "(how does|explain).*?schema"
]

File Path Triggers

Glob patterns for edited files:

"fileTriggers": {
  "pathPatterns": ["**/schema.prisma", "**/migrations/**"],
  "pathExclusions": ["**/*.test.ts"]
}

Content Pattern Triggers

Regex against file contents:

"contentPatterns": [
  "import.*[Pp]risma",
  "\\.findMany\\("
]

Skip Conditions

Prevent repeated nagging:

"skipConditions": {
  "sessionSkillUsed": true,
  "fileMarkers": ["@skip-validation"],
  "envOverride": "SKIP_MY_SKILL"
}

Troubleshooting

Skill Not Suggesting

  1. Check keywords match your prompt
  2. Test intent patterns at regex101.com
  3. Verify skill name matches in SKILL.md and skill-rules.json

Skill Not Blocking

  1. Check file path patterns (globs)
  2. Verify content patterns match file
  3. Check session state (skill may already be "used")

False Positives

  1. Make keywords more specific
  2. Narrow intent patterns
  3. Add pathExclusions for test files

Examples

Example: Library Documentation Skill

# Generate from GitHub
skill-seekers github --repo prisma/prisma --name prisma-orm
skill-seekers enhance output/prisma-orm/

# Add triggers
cat > output/prisma-orm/skill-rules-fragment.json << 'EOF'
{
  "prisma-orm": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "high",
    "promptTriggers": {
      "keywords": ["prisma", "orm", "database", "schema", "migration"],
      "intentPatterns": ["(create|query).*?(database|table|model)"]
    },
    "fileTriggers": {
      "pathPatterns": ["**/schema.prisma", "**/prisma/**/*.ts"]
    }
  }
}
EOF

# Package
skill-seekers package output/prisma-orm/

Example: Database Verification Guardrail

---
name: database-verification
description: "Verify database schema before Prisma operations"
type: skill
version: 1.0.0
---

# Database Verification

## Before Any Prisma Edit

1. Run `DESCRIBE table_name` to verify columns exist
2. Check schema.prisma for current field types
3. Verify migrations are up to date

{
  "database-verification": {
    "type": "guardrail",
    "enforcement": "block",
    "priority": "critical",
    "promptTriggers": {
      "keywords": ["prisma", "database"]
    },
    "fileTriggers": {
      "pathPatterns": ["**/services/**/*.ts"],
      "contentPatterns": ["import.*[Pp]risma"]
    },
    "blockMessage": "BLOCKED - Database Operation\n\n1. Use skill 'database-verification'\n2. Verify column names\n3. Retry edit\n\nFile: {file_path}",
    "skipConditions": {
      "sessionSkillUsed": true,
      "fileMarkers": ["@skip-validation"]
    }
  }
}