/skill-creator

name: skill-creator
description: Create, install, or update skills in the workspace. Use when (1) installing a skill from a URL or remote source, (2) creating a new skill from scratch, (3) updating or restructuring existing skills. Always use this skill for any skill installation or creation task.
license: Complete terms in LICENSE.txt

Skill Creator

This skill provides guidance for creating effective skills using the existing tool system.

About Skills

Skills are modular, self-contained packages that extend the agent's capabilities by providing specialized knowledge, workflows, and tools. They transform a general-purpose agent into a specialized agent equipped with procedural knowledge.

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 tasks

Core Principle

**Concise is Key**: Only add context the agent doesn't already have. Challenge each piece of information: "Does this justify its token cost?" Prefer concise examples over verbose explanations.

Skill Structure

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)
│   └── 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 Components

**Frontmatter (YAML)** - Required fields:

• **name**: Skill name in hyphen-case (e.g., `weather-api`, `pdf-editor`)
• **description**: **CRITICAL** - Primary triggering mechanism
• Must clearly describe what the skill does
• Must explicitly state when to use it
• Include specific trigger scenarios and keywords
• All "when to use" info goes here, NOT in body
• Example: `"PDF document processing with rotation, merging, splitting, and text extraction. Use when user needs to: (1) Rotate PDF pages, (2) Merge multiple PDFs, (3) Split PDF files, (4) Extract text from PDFs."`

**Body (Markdown)** - Loaded after skill triggers:

• Detailed usage instructions
• How to call scripts and read references
• Examples and best practices
• Use imperative/infinitive form ("Use X to do Y")

Bundled Resources

**scripts/** - When to include:

• Code is repeatedly rewritten
• Deterministic execution needed (avoid LLM randomness)
• Examples: PDF rotation, image processing
• Must test scripts before including

**references/** - When to include:

• **ONLY** when documentation is too large for SKILL.md (>500 lines)
• Database schemas, complex API specs that agent needs to reference
• Agent reads these files into context as needed
• **NOT for**: API reference docs, usage examples, tutorials (put in SKILL.md instead)
• **Rule of thumb**: If it fits in SKILL.md, don't create a separate reference file

**assets/** - When to include:

• Files used in output (not loaded to context)
• Templates, icons, boilerplate code
• Copied or modified in final output

**Important**: Most skills don't need all three. Choose based on actual needs.

What NOT to Include

Do NOT create auxiliary documentation files:

• README.md - Instructions belong in SKILL.md
• INSTALLATION_GUIDE.md - Setup info belongs in SKILL.md
• CHANGELOG.md - Not needed for local skills
• API_REFERENCE.md - Put API docs directly in SKILL.md
• USAGE_EXAMPLES.md - Put examples directly in SKILL.md
• Any other documentation files - Everything goes in SKILL.md unless it's too large

**Critical Rule**: Only create files that the agent will actually execute (scripts) or that are too large for SKILL.md (references). Documentation, examples, and guides ALL belong in SKILL.md.

Installing a Skill

Install target directory: `<workspace>/skills/<name>/` (the `<workspace>` is from the "Workspace" section).

Step 1 — Obtain skill content

| Source | Action | |---|---| | URL (single file) | Fetch content via curl or web_fetch | | URL (zip/archive) | Download and extract to a temp directory | | Local file (SKILL.md) | Read directly | | Local archive (zip) | Extract to a temp directory |

Step 2 — Identify and install

1. Locate the SKILL.md (may be at top level or inside a subdirectory) 2. Extract `name` from YAML frontmatter 3. Copy the **entire skill directory** (SKILL.md and all sibling files/folders such as `references/`, `scripts/`, `assets/`, etc.) into `<workspace>/skills/<name>/` 4. If an install/setup file exists (e.g. INSTALL.md), follow its instructions — the final result must still end up in `<workspace>/skills/<name>/`

Skill Creation Process (from scratch)

1. **Understand** - Clarify use cases with concrete examples 2. **Plan** - Identify needed scripts, references, assets 3. **Initialize** - Run init_skill.py to create template 4. **Edit** - Implement SKILL.md and resources 5. **Validate** (optional) - Run quick_validate.py to check format 6. **Iterate** - Improve based on real usage

Skill Naming

• Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
• When generating names, generate a name under 64 characters (letters, digits, hyphens).
• Prefer short, verb-led phrases that describe the action.
• Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
• Name the skill folder exactly after the skill name.

Step-by-Step Guide

Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It re