skill-creator-pro

What this skill does

# Skill Creator Pro

Professional-grade guide for creating, testing, and distributing skills. Extends the official skill-creator with 5 design patterns, description optimization, 3-stage QA, and security scanning.

## About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. They transform Claude from 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 and repetitive tasks

### Core Principles

**Concise is Key.** The context window is a public good. Only add context Claude doesn't already have. Challenge each piece of information: "Does this paragraph justify its token cost?" Prefer concise examples over verbose explanations.

**Set Appropriate Degrees of Freedom.** Match specificity to task fragility:

- **High freedom (text instructions)**: Multiple valid approaches exist; context determines best path
- **Medium freedom (pseudocode with parameters)**: Preferred patterns exist with acceptable variation
- **Low freedom (exact scripts)**: Operations are fragile, consistency critical, sequence matters

**Composability.** Assume the skill will be used alongside others. It must be a good citizen in a larger ecosystem.

**Portability.** A well-designed skill works across environments without modification.

### Anatomy of a Skill

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

#### SKILL.md (required)

- **Frontmatter** (YAML): `name` and `description` fields. These determine when Claude uses the skill. The `description` is the primary trigger mechanism.
- **Body** (Markdown): Instructions loaded only AFTER the skill triggers.

#### Scripts (`scripts/`)

- **When to include**: When the same code is repeatedly rewritten or deterministic reliability is needed
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments

#### References (`references/`)

- **When to include**: For documentation Claude should reference while working
- **Benefits**: Keeps SKILL.md lean, loaded only when needed
- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
- **Avoid duplication**: Information should live in either SKILL.md or references, not both

#### Assets (`assets/`)

- **When to include**: When the skill needs files used in the final output (templates, images, fonts)
- **Benefits**: Separates output resources from documentation

#### What NOT to Include

Do NOT create extraneous files: README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, etc. The skill should only contain information needed for an AI agent to do the job.

#### Privacy and Path References

- **Forbidden**: Absolute paths (`/home/username/`, `/Users/username/`), personal usernames, company names
- **Allowed**: Relative paths within the skill bundle (`scripts/example.py`, `references/guide.md`)

#### Versioning

Skills should NOT contain version history in SKILL.md. Versions are tracked in `marketplace.json`.

### Progressive Disclosure

Skills use a three-level loading system:

1. **Metadata (name + description)** - Always in context (~100 words)
2. **SKILL.md body** - When skill triggers (<5k words, keep under 500 lines)
3. **Bundled resources** - As needed (unlimited; scripts can execute without loading into context)

**Key principle:** When a skill supports multiple variations, keep only core workflow and selection guidance in SKILL.md. Move variant-specific details into reference files.

**Pattern 1: High-level guide with references** - Link to detailed guides from SKILL.md. Claude loads them only when needed.

**Pattern 2: Domain-specific organization** - Organize references by domain. When a user asks about sales metrics, Claude only reads `sales.md`.

**Pattern 3: Conditional details** - Show basic content, link to advanced content. Claude reads advanced files only when needed.

**Important:** Avoid deeply nested references. Keep references one level deep from SKILL.md.

## Edit Skills at Source Location

**NEVER edit skills in `~/.claude/plugins/cache/`** - that is a read-only cache directory. All changes there are lost when cache refreshes. **ALWAYS verify** the file path does NOT contain `/cache/` or `/plugins/cache/`.

## Skill Creation Process

Follow these 11 steps in order, skipping only when clearly not applicable.

### Step 1: Understand the Skill with Concrete Examples

Skip only when the skill's usage patterns are already clearly understood.

Clearly understand concrete examples of how the skill will be used. This understanding can come from direct user examples or generated examples validated with user feedback.

Relevant questions include:
- "What functionality should this skill support?"
- "Can you give examples of how this skill would be used?"
- "What would a user say that should trigger this skill?"

Avoid asking too many questions in a single message. Conclude when there is a clear sense of the functionality the skill should support.

### Step 2: Plan and Design

To turn concrete examples into an effective skill, analyze each example by:

1. Considering how to execute from scratch
2. Determining the appropriate level of freedom for Claude
3. Identifying what scripts, references, and assets would be helpful

#### Choose a Design Pattern

Select the pattern that best fits the use case. This is the most important design decision.

| Pattern | Use Case | Reference |
|:---|:---|:---|
| **Sequential Workflow** | Strict ordered steps, dependency chains | `references/pattern-1-sequential-workflow.md` |
| **Multi-MCP Coordination** | Workflows spanning multiple services | `references/pattern-2-multi-mcp-coordination.md` |
| **Iterative Refinement** | High-quality output via generate-validate-refine loops | `references/pattern-3-iterative-refinement.md` |
| **Context-Aware Tool Selection** | Best tool depends on context of request | `references/pattern-4-context-aware-tools.md` |
| **Domain-Specific Intelligence** | Embedding non-obvious expert knowledge | `references/pattern-5-domain-intelligence.md` |

Read the reference guide for the chosen pattern before proceeding.

For additional workflow patterns (sequential and conditional), see `references/workflows.md`.

#### Master the Description

The `description` in frontmatter is the primary trigger mechanism. If the skill doesn't trigger correctly, the description is the problem.

- **Formula:** `[Capability Statement]. Use when [Trigger Conditions].`
- Include keywords users are likely to say, relevant file types, and action verbs
- Include all "when to use" information here, NOT in the body
- For advanced techniques (negative triggers, debugging), see `references/advanced-description-writing.md`
- For Anthropic's official best practices, retrieve `https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md`

### Step 3: Initialize the Skill

Skip if the skill already exists and only needs iteration or packaging.

Run the `init_skill.py` script to generate a new template skill directory:

```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```

The script creates the skill directory with a SKILL.md template, TODO placeholders, and example resource directories (`scripts/`, `references/`, `a