Skill Creator

Skill Creator

This skill provides guidance for creating effective skills following the Agent Skills specification.

About Skills

Skills are modular, self-contained packages that extend AI agent capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Core Principles

Concise is Key

The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other skills' metadata, and the actual user request.

Default assumption: The agent is already very smart. Only add context it doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

Match the level of specificity to the task's fragility and variability:

High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.

Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.

Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   ├── description: (required)
│   │   └── metadata.triggers: (optional, for auto-activation)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md Frontmatter

Every SKILL.md must have YAML frontmatter with required and optional fields:

Trigger Configuration (metadata.triggers)

Skills can define auto-activation triggers in the metadata.triggers field:

metadata:
  triggers:
    type: domain           # "domain" (advisory) or "guardrail" (enforced)
    enforcement: suggest   # "suggest", "warn", or "block"
    priority: high         # "critical", "high", "medium", or "low"
    keywords:              # Exact substring matches (case-insensitive)
      - error
      - Result
      - error-stack
    intent-patterns:        # Regex patterns for intent detection
      - "\\b(handle|create)\\b.*?\\berror\\b"
      - "\\berror\\b.*?\\bhandling\\b"
    files:                  # Optional: file-based triggers
      include:
        - "**/src/**/*.rs"
      exclude:
        - "**/*.test.rs"
      content:
        - "use error_stack"

Trigger Types:

• keywords: Case-insensitive substring matching in user's prompt
• intent-patterns: Regex patterns to detect user intent (use \\b for word boundaries, .*? for non-greedy matching)
• files.include: Glob patterns for file paths
• files.exclude: Glob patterns to exclude (e.g., test files)
• files.content: Regex patterns to match file content

Enforcement Levels:

• suggest: Skill suggestion appears but doesn't block execution
• warn: Shows warning but allows proceeding
• block: Requires skill to be used before proceeding (guardrail)

Bundled Resources (optional)

Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

• When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, may be executed without loading into context

References (references/)

Documentation and reference material intended to be loaded as needed into context.

• When to include: For documentation that the agent should reference while working
• Examples: references/finance.md for financial schemas, references/api_docs.md for API specifications
• Best practice: If files are large (>10k words), include grep search patterns in SKILL.md

Assets (assets/)

Files not intended to be loaded into context, but rather used within the output.

• When to include: When the skill needs files that will be used in the final output
• Examples: assets/logo.png for brand assets, assets/template.pptx for templates

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words) 2. SKILL.md body - When skill triggers (<5k words recommended) 3. Bundled resources - As needed (unlimited)

Keep SKILL.md body under 500 lines. Split content into separate files when approaching this limit.

Pattern: High-level guide with references

# PDF Processing

## Quick start
Extract text with pdfplumber: [code example]

## Advanced features
- **Form filling**: See [FORMS.md](references/FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](references/REFERENCE.md) for all methods

Pattern: Domain-specific organization

bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    └── product.md (API usage, features)

Skill Creation Process

Step 1: Understanding the Skill with Concrete Examples

To create an effective skill, clearly understand concrete examples of how the skill will be used:

• "What functionality should the skill support?"
• "Can you give some examples of how this skill would be used?"
• "What would a user say that should trigger this skill?"

Step 2: Planning the Reusable Skill Contents

Analyze each example to identify what scripts, references, and assets would be helpful:

• Scripts: Code that gets rewritten repeatedly (e.g., scripts/rotate_pdf.py)
• Assets: Boilerplate templates (e.g., assets/hello-world/ for frontend projects)
• References: Schemas and documentation (e.g., references/schema.md)

Step 3: Initializing the Skill

When creating a new skill from scratch, run the init command:

yarn agents:skill-management init <skill-name>

The command creates the skill directory in .claude/skills/ with a SKILL.md template and example resource directories.

Step 4: Edit the Skill

Write the Frontmatter

---
name: my-skill
description: What the skill does and when to use it. Include trigger keywords.
license: Apache-2.0
metadata:
  triggers:
    type: domain
    enforcement: suggest
    priority: medium
    keywords:
      - keyword1
      - keyword2
    intent-patterns:
      - "\\b(create|add)\\b.*?\\bsomething\\b"
---

Description best practices:

• Include both what the skill does and specific triggers/contexts
• Include all "when to use" information here - the body is only loaded after triggering
• Max 1024 characters

Write the Body

Write instructions for using the skill. Keep under 500 lines.

Step 5: Generate and Validate Skill Rules

After creating/modifying skills, validate and regenerate the skill-rules.json:

yarn agents:skill-management validate
yarn agents:skill-management generate-skill-rules

Step 6: Test the Skill

Test with a specific prompt:

echo '{"session_id":"test","prompt":"your test prompt","cwd":"."}' | \
  yarn workspace @local/claude-hooks run:skill

Debug matching logic:

echo '{"session_id":"test","prompt":"your test prompt","cwd":"."}' | \
  yarn workspace @local/claude-hooks dev:skill

Reference Files

For detailed information on specific topics, see:

• [references/workflows.md](references/workflows.md): Sequential and conditional workflow patterns
• [references/output-patterns.md](references/output-patterns.md): Template and example patterns for consistent output
• [references/patterns-library.md](references/patterns-library.md): Ready-to-use regex and glob patterns for triggers
• [references/troubleshooting.md](references/troubleshooting.md): Debugging guide for skill activation issues

Testing Checklist

• [ ] Skill file created in .claude/skills/{name}/SKILL.md
• [ ] Proper frontmatter with name and description
• [ ] Triggers configured in metadata.triggers
• [ ] skill-rules.json regenerated
• [ ] Keywords tested with real prompts
• [ ] Intent patterns tested with variations
• [ ] SKILL.md under 500 lines
• [ ] Reference files created if needed

Reference Documentation for {{skill_title}}

This is a placeholder for detailed reference documentation. Replace with actual reference content or delete if not needed.

Example real reference docs from other skills:

• product-management/references/communication.md - Comprehensive guide for status updates
• product-management/references/context_building.md - Deep-dive on gathering context
• bigquery/references/ - API references and query examples

When Reference Docs Are Useful

Reference docs are ideal for:

• Comprehensive API documentation
• Detailed workflow guides
• Complex multi-step processes
• Information too lengthy for main SKILL.md
• Content that's only needed for specific use cases

Structure Suggestions

API Reference Example

• Overview
• Authentication
• Endpoints with examples
• Error codes
• Rate limits

Workflow Guide Example

• Prerequisites
• Step-by-step instructions
• Common patterns
• Troubleshooting
• Best practices

{{skill_title}}

Overview

[TODO: 1-2 sentences explaining what this skill enables]

Structuring This Skill

[TODO: Choose the structure that best fits this skill's purpose. Common patterns:

1. Workflow-Based (best for sequential processes)

• Works well when there are clear step-by-step procedures
• Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
• Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...

2. Task-Based (best for tool collections)

• Works well when the skill offers different operations/capabilities
• Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
• Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...

3. Reference/Guidelines (best for standards or specifications)

• Works well for brand guidelines, coding standards, or requirements
• Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
• Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...

4. Capabilities-Based (best for integrated systems)

• Works well when the skill provides multiple interrelated features
• Example: Product Management with "Core Capabilities" → numbered capability list
• Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...

Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).

Delete this entire "Structuring This Skill" section when done - it's just guidance.]

[TODO: Replace with the first main section based on chosen structure]

[TODO: Add content here. See examples in existing skills:

• Code samples for technical skills
• Decision trees for complex workflows
• Concrete examples with realistic user requests
• References to scripts/templates/references as needed]

Resources

This skill includes example resource directories that demonstrate how to organize different types of bundled resources:

scripts/

Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

Examples from other skills:

• PDF skill: fill_fillable_fields.py, extract_form_field_info.py - utilities for PDF manipulation
• DOCX skill: document.py, utilities.py - Python modules for document processing

Appropriate for: Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

Note: Scripts may be executed without loading into context, but can still be read by the agent for patching or environment adjustments.

references/

Documentation and reference material intended to be loaded into context to inform the agent's process and thinking.

Examples from other skills:

• Product management: communication.md, context_building.md - detailed workflow guides
• BigQuery: API reference documentation and query examples
• Finance: Schema documentation, company policies

Appropriate for: In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that the agent should reference while working.

assets/

Files not intended to be loaded into context, but rather used within the output the agent produces.

Examples from other skills:

• Brand guidelines: PowerPoint template files (.pptx), logo files
• Frontend builder: HTML/React boilerplate project directories
• Typography: Font files (.ttf, .woff2)

Appropriate for: Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

---

Any unneeded directories can be deleted. Not every skill requires all three types of resources.

Attribution & Changelog

Attribution

This skill is based on and incorporates content from:

• Anthropic's Claude Code skill-creator - Original skill creation guidance and best practices
• Agent Skills Specification - https://agentskills.io/specification

Changelog

2025-06-18 - Vendor-Agnostic Rewrite

Breaking Changes:

• Trigger configuration moved from skill-rules.json to metadata.triggers in each skill's SKILL.md frontmatter
• Must regenerate skill-rules.json using yarn agents:skill-management generate-skill-rules after modifying skills

Changes:

1. Vendor-Agnostic Language

• Replaced all "Claude" references with generic "agent" terminology
• Now compatible with any AI agent that supports the Agent Skills specification

2. Follows Agent Skills Specification

• Updated frontmatter to follow https://agentskills.io/specification
• Added documentation for all spec fields: name, description, license, compatibility, metadata, allowed-tools

3. Trigger Configuration in Frontmatter

• Triggers now defined in metadata.triggers within each SKILL.md
• Single source of truth - no separate configuration file to maintain
• Supports: type, enforcement, priority, keywords, intent-patterns, files

4. New Commands

• yarn agents:skill-management - TypeScript-based skill management CLI
• Commands: init, validate, generate-skill-rules

5. Merged Content from writing-skills

• Incorporated trigger type documentation
• Added testing and validation workflows
• Included debugging guidance

Migration:

To migrate existing skills to the new format:

1. Add metadata.triggers to your SKILL.md frontmatter:

   metadata:
     triggers:
       type: domain
       enforcement: suggest
       priority: medium
       keywords:
         - keyword1
       intent-patterns:
         - "\\b(pattern)\\b"

2. Regenerate skill-rules.json:

   yarn agents:skill-management generate-skill-rules

Output Patterns

Use these patterns when skills need to produce consistent, high-quality output.

Template Pattern

Provide templates for output format. Match the level of strictness to your needs.

For strict requirements (like API responses or data formats):

## Report structure

ALWAYS use this exact template structure:

# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation

For flexible guidance (when adaptation is useful):

## Report structure

Here is a sensible default format, but use your best judgment:

# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

## Recommendations
[Tailor to the specific context]

Adjust sections as needed for the specific analysis type.

Examples Pattern

For skills where output quality depends on seeing examples, provide input/output pairs:

## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:

fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

Follow this style: type(scope): brief description, then detailed explanation.

Examples help agents understand the desired style and level of detail more clearly than descriptions alone.

Common Patterns Library

Ready-to-use regex and glob patterns for skill triggers. Copy and customize for your skills.

Intent Patterns (Regex)

Use in metadata.triggers.intent-patterns. Remember to escape backslashes in YAML (\\b not \b).

Error Handling

(handle|create|define|propagate).*?error
(error|errors).*?(handling|propagation|definition|documentation)
Result.*?Report
(fix|handle|catch|debug).*?(error|exception|bug)

Dependencies/Package Management

(add|create|update|modify).*?(dependency|dependencies|crate|package)
(cargo|npm|yarn|pip).*?(dependency|dependencies|install)
workspace.*?dependency

Feature/Endpoint Creation

(add|create|implement|build).*?(feature|endpoint|route|service|API)

Component Creation (Frontend)

(create|add|make|build).*?(component|UI|page|modal|dialog|form)

Database/Schema Work

(add|create|modify|update).*?(entity|type|property|table|migration|schema)
(database|graph|sql).*?(change|update|query)

Explanation Requests

(how does|how do|explain|what is|describe|tell me about).*?

Workflow Operations

(create|add|modify|update).*?(workflow|step|branch|condition)
(debug|troubleshoot|fix).*?workflow

Testing

(write|create|add|run).*?(test|spec|unit.*?test)

File Path Patterns (Glob)

Use in metadata.triggers.files.include.

By Language

**/*.rs                     # All Rust files
**/*.ts                     # All TypeScript files
**/*.tsx                    # All React/TSX files
**/*.py                     # All Python files
**/*.go                     # All Go files

By Location

src/**/*.ts                 # Source files
lib/**/*.ts                 # Library files
apps/**/*                   # Application code
libs/**/*                   # Shared libraries

Test Exclusions

Use in metadata.triggers.files.exclude:

**/*.test.ts                # TypeScript tests
**/*.test.tsx               # React tests
**/*.spec.ts                # Spec files
**/*.test.rs                # Rust tests
**/tests/**                 # Test directories
**/test/**                  # Test directories
**/__tests__/**             # Jest test directories

Configuration Files

**/Cargo.toml               # Rust manifest
**/package.json             # Node manifest
**/tsconfig.json            # TypeScript config
**/*.config.js              # Config files

Content Patterns (Regex)

Use in metadata.triggers.files.content. These match against file contents.

Rust

Result<                         # Result types
Report<                         # error-stack Report
\\.attach                       # attach() method
\\.change_context              # change_context() method
use error_stack                 # error-stack imports
impl.*Error for                 # Error trait implementations

TypeScript/React

export.*React\\.FC             # React functional components
export default function.*       # Default function exports
useState|useEffect|useMemo      # React hooks
import.*from                    # ES imports

Error Handling

try\\s*\\{                     # Try blocks
catch\\s*\\(                   # Catch blocks
throw new                       # Throw statements

Example Usage

metadata:
  triggers:
    type: domain
    enforcement: suggest
    priority: high
    keywords:
      - error
      - error handling
    intent-patterns:
      - "\\b(handle|create|fix)\\b.*?\\berror\\b"
      - "\\berror\\b.*?\\b(handling|propagation)\\b"
    files:
      include:
        - "**/*.rs"
      exclude:
        - "**/*.test.rs"
      content:
        - "Result<"
        - "Report<"

Best Practices

DO:

• Use \\b for word boundaries (prevents partial matches)
• Use .*? for non-greedy matching (faster, more precise)
• Escape special regex characters: \\. for literal dot
• Test patterns at https://regex101.com/
• Start specific, broaden if needed

DON'T:

• Use overly generic keywords ("system", "work", "create" alone)
• Make patterns too broad (causes false positives)
• Use greedy .* instead of non-greedy .*?
• Forget to escape backslashes in YAML (use \\b not \b)

Troubleshooting - Skill Activation Issues

Debugging guide for skill activation problems.

Skill Not Triggering

Keywords Don't Match

Symptoms: Skill should trigger but doesn't.

Check:

• Look at metadata.triggers.keywords in SKILL.md
• Keywords use case-insensitive substring matching
• Verify keywords are actually in the prompt

Example:

keywords:
  - layout
  - grid

• "how does the layout work?" → ✅ Matches "layout"
• "how does the grid system work?" → ✅ Matches "grid"
• "how does it work?" → ❌ No match

Fix: Add more keyword variations

Intent Patterns Too Specific

Check:

• Look at metadata.triggers.intent-patterns
• Test regex at https://regex101.com/
• May need broader patterns

Example:

intent-patterns:
  - "(create|add).*?(database.*?table)"  # Too specific

• "create a database table" → ✅ Matches
• "add new table" → ❌ Doesn't match (missing "database")

Fix: Broaden the pattern:

intent-patterns:
  - "(create|add).*?(table|database)"  # Better

Name Mismatch

Check:

• Skill name in SKILL.md frontmatter
• Skill directory name
• Must match exactly

Fix: Make names match exactly

YAML Syntax Error

Check:

yarn agents:skill-management validate

Common errors:

• Incorrect indentation
• Missing quotes around regex patterns
• Unescaped special characters

False Positives

Symptoms: Skill triggers when it shouldn't.

Keywords Too Generic

Problem:

keywords:
  - user
  - system
  - create

Triggers on: "user manual", "file system", "create directory"

Solution: Make keywords more specific:

keywords:
  - user authentication
  - user tracking
  - create feature

Intent Patterns Too Broad

Problem:

intent-patterns:
  - "(create)"  # Matches everything with "create"

Solution: Add context:

intent-patterns:
  - "(create|add).*?(database|table|feature)"

File Paths Too Generic

Problem:

files:
  include:
    - "src/**"  # Matches everything in src/

Solution: Use narrower patterns:

files:
  include:
    - "src/services/**/*.ts"
    - "src/controllers/**/*.ts"

Debugging Commands

Validate Configuration

yarn agents:skill-management validate

Regenerate Rules

yarn agents:skill-management generate-skill-rules

Check Generated Output

cat .claude/skills/skill-rules.json | jq '.skills["my-skill"]'

Common Validation Errors

"Name does not match directory"

The name field in SKILL.md must exactly match the directory name.

skill-creator/SKILL.md
---
name: skill-creator  # Must match directory name

"Invalid regex in intent-patterns"

Test your regex at https://regex101.com/ first.

Common issues:

• Unescaped special characters (use \\. for literal dot)
• Missing escape for backslash in YAML (use \\b not \b)

"Description too long"

Description must be under 1024 characters. Move detailed content to the SKILL.md body.

Workflow Patterns

Sequential Workflows

For complex tasks, break operations into clear, sequential steps. It is often helpful to give the agent an overview of the process towards the beginning of SKILL.md:

Filling a PDF form involves these steps:

1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Validate mapping (run validate_fields.py)
4. Fill the form (run fill_form.py)
5. Verify output (run verify_output.py)

Conditional Workflows

For tasks with branching logic, guide the agent through decision points:

1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow: [steps]
3. Editing workflow: [steps]