building-skill

Skill Builder

Create complete, production-ready Agent Skills from natural language descriptions. This skill guides you through understanding requirements, planning structure, and generating all necessary files.

What This Skill Produces

A complete skill package ready for distribution:

skill-name/
├── SKILL.md              # Core instructions + metadata
├── scripts/              # Executable automation (Python, Bash)
├── references/           # Documentation loaded into context as needed
├── assets/              # Templates, icons, boilerplate (used in output)
└── examples/            # Input/output examples for testing

Workflow Overview

flowchart LR
    A[Gather Requirements] --> B[Plan Skill Structure]
    B --> C[Generate Core SKILL.md]
    C --> D[Create Bundled Resources]
    D --> E[Generate Test Cases]
    E --> F[Validate & Package]

---

Step 1: Gather Requirements

Ask targeted questions to understand the skill's purpose. Avoid overwhelming—start with essentials:

Required Information

1. Primary Purpose: "What should this skill help accomplish?"
2. Trigger Scenarios: "What would a user say or do that should activate this skill?"
3. Concrete Examples: "Give me 2-3 specific examples of how you'd use this skill."

Contextual Questions (as needed)

• Input/Output Format: "What input does the skill receive? What should it produce?"
• Degree of Freedom: "Should the output be strictly formatted or flexible?"
• External Dependencies: "Does this require specific tools, APIs, or file types?"
• Domain Knowledge: "Is there specialized knowledge the skill needs?"

Conclude Step 1 When

You can describe:

• 3+ concrete usage examples
• Clear trigger conditions
• Expected input/output patterns
• Any special requirements or constraints

---

Step 2: Plan Skill Structure

Analyze each concrete example to determine what reusable resources to include.

Decision Framework

For each example, ask:

Question	If YES → Include
Does it require repetitive code?	scripts/ - executable utilities
Does it need domain knowledge?	references/ - documentation
Does it use templates/boilerplate?	assets/ - files used in output
Does it benefit from examples?	examples/ - input/output pairs

Resource Planning Template

## Planned Resources for [skill-name]

### scripts/
- [ ] script_name.py - Purpose: [what it does]

### references/
- [ ] topic.md - Purpose: [what knowledge it provides]

### assets/
- [ ] template.ext - Purpose: [how it's used in output]

### examples/
- [ ] example_input.txt → example_output.txt

Structure Patterns

1. Workflow-Based (sequential processes)

• Structure: Overview → Decision Tree → Step 1 → Step 2...
• Best for: Multi-step procedures with clear phases
• Example: Document processing, deployment pipelines

2. Task-Based (tool collections)

• Structure: Overview → Quick Start → Task Category 1 → Task Category 2...
• Best for: Skills with multiple independent operations
• Example: PDF tools, image editor, file utilities

3. Reference/Guidelines (standards or specs)

• Structure: Overview → Guidelines → Specifications → Usage...
• Best for: Brand guidelines, coding standards, documentation
• Example: Style guide, API documentation generator

4. Capabilities-Based (integrated systems)

• Structure: Overview → Core Capabilities → Feature 1 → Feature 2...
• Best for: Skills with interrelated features
• Example: Project management, CRM integration

---

Step 3: Generate SKILL.md

Frontmatter Requirements

---
name: skill-name           # Required: lowercase, hyphens only, ≤64 chars
description: [detailed]    # Required: what + when to use, ≤1024 chars
license: MIT               # Optional: license identifier
metadata:                  # Optional: custom key-value pairs
  author: name
  version: "1.0"
  category: system         # Required: system or domain
---

Description Best Practices

The description is the PRIMARY trigger mechanism. Include:

1. What the skill does - Clear capability statement
2. When to use it - Specific triggers, scenarios, file types
3. Keywords - Terms that might appear in user requests

Good Example:

description: Creates data visualizations from CSV, JSON, or SQL query results. Use when the user asks for charts, graphs, dashboards, or wants to visualize data. Supports bar, line, pie, scatter, and heatmap chart types with customizable styling.

Bad Example:

description: Helps with data visualization.

Body Guidelines

Write instructions as if onboarding another AI agent:

• Use imperative form: "Generate the report" not "You should generate"
• Be specific, not verbose: Prefer examples over explanations
• Reference resources with paths: See [schema](references/schema.md)
• Keep under 500 lines: Split longer content into references

Body Structure Template

# [Skill Title]

[1-2 sentence overview]

## Quick Start

[Minimal steps to use the skill for the most common case]

## Core Workflow

[Main procedures with decision points]

## Reference

- [Topic 1](references/topic1.md) - When to consult
- [Topic 2](references/topic2.md) - When to consult

## Resources

List of bundled scripts/assets with brief descriptions.

---

Step 4: Create Bundled Resources

scripts/ Directory

Executable code that performs specific operations.

Guidelines:

• Make scripts self-contained or document dependencies clearly
• Include helpful error messages and validation
• Use Python or Bash for maximum compatibility
• Add usage documentation in script docstrings

Script Template (Python):

#!/usr/bin/env python3
"""
[Brief description of what this script does]

Usage:
    python script_name.py <arg1> [arg2]

Example:
    python script_name.py input.txt --format json
"""

import sys

def main():
    if len(sys.argv) < 2:
        print("Usage: script_name.py <arg1> [arg2]")
        sys.exit(1)
    
    # Implementation here
    
if __name__ == "__main__":
    main()

references/ Directory

Documentation loaded into context as needed. Keep individual files focused.

Guidelines:

• <10k words per file (recommend <5k)
• Include table of contents for files >100 lines
• Organize by domain/category when skill spans multiple areas
• Avoid duplicating content from SKILL.md

Reference File Template:

# [Topic] Reference

## Overview
[Brief context for when to use this reference]

## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)

## Section 1
[Detailed content]

## Section 2
[Detailed content]

assets/ Directory

Files used in the output Claude produces (not loaded into context).

Common Asset Types:

• Templates: .pptx, .docx, boilerplate directories
• Images: .png, .svg, brand assets
• Fonts: .ttf, .woff2
• Data: .csv, .json schemas

examples/ Directory

Input/output pairs demonstrating skill usage.

Example Structure:

examples/
├── basic/
│   ├── input.txt
│   └── expected_output.txt
├── advanced/
│   ├── input.json
│   └── expected_output.json
└── edge_cases/
    ├── empty_input.txt
    └── expected_output.txt

---

Step 5: Generate Test Cases

Create test cases that verify the skill works correctly.

Test Case Template

# Test Cases for [skill-name]

## Test 1: [Basic functionality]
**Input:** [User request or input file]
**Expected:** [What the skill should produce]
**Verification:** [How to confirm success]

## Test 2: [Edge case]
**Input:** [Edge case scenario]
**Expected:** [Correct handling]
**Verification:** [How to confirm]

## Test 3: [Error handling]
**Input:** [Invalid input]
**Expected:** [Graceful error message]
**Verification:** [Error is clear and actionable]

---

Step 6: Validate & Package

Validation Checklist

Run through before finalizing:

• name matches directory name exactly
• name is lowercase with hyphens only (no underscores)
• description explains both WHAT and WHEN
• description includes relevant keywords/triggers
• SKILL.md body is under 500 lines
• All referenced files exist at specified paths
• Scripts are executable and tested
• Examples produce expected output

Validation Script

Use ./scripts/validate_skill.py to check structure:

python .github/skills/building-skill/scripts/validate_skill.py path/to/skill-name

Final Delivery

Provide the complete skill as:

1. File listing with paths
2. Full file contents for each file
3. Installation instructions (copy to .github/skills/)
4. Test commands to verify functionality

---

Anti-Patterns to Avoid

Anti-Pattern	Problem	Solution
README.md in skill	Unnecessary clutter	All info goes in SKILL.md
"When to Use" in body	Not visible before activation	Put in description field
Verbose explanations	Wastes context tokens	Use examples instead
Deeply nested references	Hard to navigate	Max 1 level from SKILL.md
Duplicated content	Inconsistency risk	Single source of truth
Untested scripts	Runtime failures	Test before packaging

---

Progressive Disclosure Patterns

Pattern 1: High-level guide with references

Keep SKILL.md lean, link to details:

## Advanced Features

- **Form filling**: See [FORMS.md](references/forms.md) for complete guide
- **API reference**: See [API.md](references/api.md) for all methods

Pattern 2: Domain-specific organization

Organize by domain when skill spans multiple areas:

my-skill/
├── SKILL.md (overview + navigation)
└── references/
    ├── domain1.md (loaded only when relevant)
    ├── domain2.md
    └── domain3.md

---

Example: Creating a Skill

User Request: "I want a skill that helps m

---

Content truncated.