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
Canonical builder workflow New Seer skill/plugin/hook development via Innovation standards 30-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 (per the Agent Skills Spec):

Frontmatter:

  • name: Max 64 characters, lowercase + hyphens only
  • description: Max 1024 characters
  • Write in third person ("Applies..." not "I help...")

Body (progressive disclosure):

  • SKILL.md body: Max 500 lines (Anthropic spec recommendation — keeps the skill loadable in ≤5000 tokens)
  • Move detailed reference material, schemas, examples, and procedures to resources/*.md files — they load on-demand, not at activation
  • Keep file references one level deep from SKILL.md (avoid deeply nested reference chains)

Distribution:

  • Claude.ai supports plugin uploads (not just individual skills) — bundle related skills into a plugin via marketplace.json and upload as a single .zip when you want to ship multiple skills together

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

Canonical Skill Development Workflow

The legacy CLI generation path is no longer supported in this repository.

Use the inn-seer-agent-skill-developer skill as the canonical workflow for:

  • Creating new skills
  • Updating existing skills
  • Designing skill activation rules
  • Validating quality and architecture alignment

See plugins/divisions/innovation/skills/inn-seer-agent-skill-developer/ for the current process and implementation standards.

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: Canonical Builder Workflow

Use inn-seer-agent-skill-developer to draft the skill structure, frontmatter, trigger patterns, and quality checks before packaging.

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"]
    }
  }
}