skill-creator

name	skill-creator
description	Creates new AI agent skills following a generic Agent Skills specification. Trigger: When user asks to create a new skill, add agent instructions, or document patterns for AI.
allowed-tools	Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task

Skill Creator Guide

This guide outlines how to create new AI agent skills following a generic Agent Skills specification. It covers when to create a skill, the skill structure, naming conventions, frontmatter fields, content guidelines, and registration.

When to Create a Skill

Create a skill when:

• A pattern is used repeatedly and AI needs guidance
• Project-specific conventions differ from generic best practices
• Complex workflows need step-by-step instructions
• Decision trees help AI choose the right approach

Don't create a skill when:

• Documentation already exists (create a reference instead)
• Pattern is trivial or self-explanatory
• It's a one-off task

---

Skill Structure

skills/{skill-name}/
├── SKILL.md              # Required - main skill file
├── assets/               # Optional - templates, schemas, examples
│   ├── template.py
│   └── schema.json
└── references/           # Optional - links to local docs
    └── docs.md           # Points to docs/developer-guide/*.mdx

---

SKILL.md Template

---
name: {skill-name}
description: >
  {One-line description of what this skill does}.
  Trigger: {When the AI should load this skill}.
license: Apache-2.0
metadata:
  author: generic-author
  version: "1.0"
---

## When to Use

{Bullet points of when to use this skill}

## Critical Patterns

{The most important rules - what AI MUST know}

## Code Examples

{Minimal, focused examples}

## Commands

```bash
{Common commands}

Resources

• Templates: See assets/ for {description}
• Documentation: See references/ for local docs

---

## Naming Conventions

| Type | Pattern | Examples |
|------|---------|----------|
| Generic skill | `{technology}` | `pytest`, `playwright`, `typescript` |
| Repo-specific | `{repo}-{component}` | `repo-api`, `repo-ui`, `repo-sdk-check` |
| Testing skill | `test-{component}` | `test-sdk`, `test-api` |
| Workflow skill | `{action}-{target}` | `skill-creator`, `jira-task` |

---

## Decision: assets/ vs references/

Need code templates? → assets/ Need JSON schemas? → assets/ Need example configs? → assets/ Link to existing docs? → references/ Link to external guides? → references/ (with local path)

**Key Rule**: `references/` should point to LOCAL files (`docs/developer-guide/*.mdx`), not web URLs.

---

## Decision: Repo-Specific vs Generic

Patterns apply to ANY project? → Generic skill (e.g., pytest, typescript) Patterns are repo-specific? → {repo}-{name} skill Generic skill needs repo info? → Add references/ pointing to repo docs

---

## Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill identifier (lowercase, hyphens) |
| `description` | Yes | What + Trigger in one block |
| `license` | Yes | Always `Apache-2.0` |
| `metadata.author` | Yes | `generic-author` |
| `metadata.version` | Yes | Semantic version as string |

---

## Content Guidelines

### DO
- Start with the most critical patterns
- Use tables for decision trees
- Keep code examples minimal and focused
- Include Commands section with copy-paste commands

### DON'T
- Add Keywords section (agent searches frontmatter, not body)
- Duplicate content from existing docs (reference instead)
- Include lengthy explanations (link to docs)
- Add troubleshooting sections (keep focused)
- Use web URLs in references (use local paths)

---

## Registering the Skill

After creating the skill, add it to `AGENTS.md`:

```markdown
| `{skill-name}` | {Description} | [SKILL.md](skills/{skill-name}/SKILL.md) |

---

Checklist Before Creating

• Skill doesn't already exist (check skills/)
• Pattern is reusable (not one-off)
• Name follows conventions
• Frontmatter is complete (description includes trigger keywords)
• Critical patterns are clear
• Code examples are minimal
• Commands section exists
• Added to AGENTS.md

Resources - Assets and References

• Templates: See assets/ for SKILL.md template