write-a-skill

# Writing Skills

> Derived from [Matt Pocock's write-a-skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill) (MIT). Matt's voice and 3-phase workflow preserved verbatim. Additions: validation tools + references + cs-* wrapper (see *Tooling + Companions* below).

## Process

1. **Gather requirements** - ask user about:
   - What task/domain does the skill cover?
   - What specific use cases should it handle?
   - Does it need executable scripts or just instructions?
   - Any reference materials to include?

2. **Draft the skill** - create:
   - SKILL.md with concise instructions
   - Additional reference files if content exceeds 500 lines
   - Utility scripts if deterministic operations needed

3. **Review with user** - present draft and ask:
   - Does this cover your use cases?
   - Anything missing or unclear?
   - Should any section be more/less detailed?

## Skill Structure

```
skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js
```

## SKILL.md Template

```md
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
```

## Description Requirements

The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.

**Goal**: Give your agent just enough info to know:

1. What capability this skill provides
2. When/why to trigger it (specific keywords, contexts, file types)

**Format**:

- Max 1024 chars
- Write in third person
- First sentence: what it does
- Second sentence: "Use when [specific triggers]"

**Good example**:

```
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

**Bad example**:

```
Helps with documents.
```

The bad example gives your agent no way to distinguish this from other document skills.

## When to Add Scripts

Add utility scripts when:

- Operation is deterministic (validation, formatting)
- Same code would be generated repeatedly
- Errors need explicit handling

Scripts save tokens and improve reliability vs generated code.

## When to Split Files

Split into separate files when:

- SKILL.md exceeds 100 lines
- Content has distinct domains (finance vs sales schemas)
- Advanced features are rarely needed

## Review Checklist

After drafting, verify:

- [ ] Description includes triggers ("Use when...")
- [ ] SKILL.md under 100 lines
- [ ] No time-sensitive info
- [ ] Consistent terminology
- [ ] Concrete examples included
- [ ] References one level deep

## Tooling + Companions

Validation tools + cs-* wrapper sit alongside this skill. Run all 6 review-checklist items programmatically:

```
python scripts/skill_review_checklist_runner.py path/to/skill-folder
```

See [references/companion_tooling.md](references/companion_tooling.md) for the tool catalogue, cs-skill-author persona agent, and `/cs-write-a-skill` slash command.

## When the knowledge is in a document, not your head

This skill authors from expertise you already have. When the source is a book, a docs folder,
a standard, or a pile of specs, use `engineering/book-to-skill` instead — it compiles the
document into a knowledge-base skill (core frameworks + on-demand chapters + glossary +
patterns + cheatsheet) and can package the result as a plugin.

```
/cs-book-to-skill <path|folder|glob> [skill-name]     # compile the source
/cs-book-to-plugin <compiled-skill-dir>               # wrap it as a plugin
```

Rule of thumb: **author first, compile second.** A hand-written skill states what you want the
agent to do; a compiled book skill is the reference it consults while doing it. If you have
both, they are two skills, not one.

---

**Version:** 1.0.0
**Derived:** Matt Pocock (MIT) + this repo's wrapper

{
  "format": "aiskill/v1",
  "skill": {
    "name": "write-a-skill",
    "slug": "write-a-skill",
    "version": "1.0.0",
    "description": "Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.",
    "category": "Development",
    "tags": [
      "ai-agents",
      "agents"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Writing Skills\r\n\r\n> Derived from [Matt Pocock's write-a-skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill) (MIT). Matt's voice and 3-phase workflow preserved verbatim. Additions: validation tools + references + cs-* wrapper (see *Tooling + Companions* below).\r\n\r\n## Process\r\n\r\n1. **Gather requirements** - ask user about:\r\n   - What task/domain does the skill cover?\r\n   - What specific use cases should it handle?\r\n   - Does it need executable scripts or just instructions?\r\n   - Any reference materials to include?\r\n\r\n2. **Draft the skill** - create:\r\n   - SKILL.md with concise instructions\r\n   - Additional reference files if content exceeds 500 lines\r\n   - Utility scripts if deterministic operations needed\r\n\r\n3. **Review with user** - present draft and ask:\r\n   - Does this cover your use cases?\r\n   - Anything missing or unclear?\r\n   - Should any section be more/less detailed?\r\n\r\n## Skill Structure\r\n\r\n```\r\nskill-name/\r\n├── SKILL.md           # Main instructions (required)\r\n├── REFERENCE.md       # Detailed docs (if needed)\r\n├── EXAMPLES.md        # Usage examples (if needed)\r\n└── scripts/           # Utility scripts (if needed)\r\n    └── helper.js\r\n```\r\n\r\n## SKILL.md Template\r\n\r\n```md\r\n---\r\nname: skill-name\r\ndescription: Brief description of capability. Use when [specific triggers].\r\n---\r\n\r\n# Skill Name\r\n\r\n## Quick start\r\n\r\n[Minimal working example]\r\n\r\n## Workflows\r\n\r\n[Step-by-step processes with checklists for complex tasks]\r\n\r\n## Advanced features\r\n\r\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\r\n```\r\n\r\n## Description Requirements\r\n\r\nThe description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.\r\n\r\n**Goal**: Give your agent just enough info to know:\r\n\r\n1. What capability this skill provides\r\n2. When/why to trigger it (specific keywords, contexts, file types)\r\n\r\n**Format**:\r\n\r\n- Max 1024 chars\r\n- Write in third person\r\n- First sentence: what it does\r\n- Second sentence: \"Use when [specific triggers]\"\r\n\r\n**Good example**:\r\n\r\n```\r\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\r\n```\r\n\r\n**Bad example**:\r\n\r\n```\r\nHelps with documents.\r\n```\r\n\r\nThe bad example gives your agent no way to distinguish this from other document skills.\r\n\r\n## When to Add Scripts\r\n\r\nAdd utility scripts when:\r\n\r\n- Operation is deterministic (validation, formatting)\r\n- Same code would be generated repeatedly\r\n- Errors need explicit handling\r\n\r\nScripts save tokens and improve reliability vs generated code.\r\n\r\n## When to Split Files\r\n\r\nSplit into separate files when:\r\n\r\n- SKILL.md exceeds 100 lines\r\n- Content has distinct domains (finance vs sales schemas)\r\n- Advanced features are rarely needed\r\n\r\n## Review Checklist\r\n\r\nAfter drafting, verify:\r\n\r\n- [ ] Description includes triggers (\"Use when...\")\r\n- [ ] SKILL.md under 100 lines\r\n- [ ] No time-sensitive info\r\n- [ ] Consistent terminology\r\n- [ ] Concrete examples included\r\n- [ ] References one level deep\r\n\r\n## Tooling + Companions\r\n\r\nValidation tools + cs-* wrapper sit alongside this skill. Run all 6 review-checklist items programmatically:\r\n\r\n```\r\npython scripts/skill_review_checklist_runner.py path/to/skill-folder\r\n```\r\n\r\nSee [references/companion_tooling.md](references/companion_tooling.md) for the tool catalogue, cs-skill-author persona agent, and `/cs-write-a-skill` slash command.\r\n\r\n## When the knowledge is in a document, not your head\r\n\r\nThis skill authors from expertise you already have. When the source is a book, a docs folder,\r\na standard, or a pile of specs, use `engineering/book-to-skill` instead — it compiles the\r\ndocument into a knowledge-base skill (core frameworks + on-demand chapters + glossary +\r\npatterns + cheatsheet) and can package the result as a plugin.\r\n\r\n```\r\n/cs-book-to-skill <path|folder|glob> [skill-name]     # compile the source\r\n/cs-book-to-plugin <compiled-skill-dir>               # wrap it as a plugin\r\n```\r\n\r\nRule of thumb: **author first, compile second.** A hand-written skill states what you want the\r\nagent to do; a compiled book skill is the reference it consults while doing it. If you have\r\nboth, they are two skills, not one.\r\n\r\n---\r\n\r\n**Version:** 1.0.0\r\n**Derived:** Matt Pocock (MIT) + this repo's wrapper",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The write-a-skill/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/write-a-skill",
    "exported_at": "2026-11-03T07:42:36.469Z"
  }
}

format: aiskill/v1
skill:
  name: write-a-skill
  slug: write-a-skill
  version: 1.0.0
  description: >-
    Create new agent skills with proper structure, progressive disclosure, and bundled resources.
    Use when user wants to create, write, build, or author a new skill.
  category: Development
  tags:
    - ai-agents
    - agents
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Writing Skills\r\n\r\n> Derived from [Matt Pocock's write-a-skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill) (MIT). Matt's voice and 3-phase workflow preserved verbatim. Additions: validation tools + references + cs-* wrapper (see *Tooling + Companions* below).\r\n\r\n## Process\r\n\r\n1. **Gather requirements** - ask user about:\r\n   - What task/domain does the skill cover?\r\n   - What specific use cases should it handle?\r\n   - Does it need executable scripts or just instructions?\r\n   - Any reference materials to include?\r\n\r\n2. **Draft the skill** - create:\r\n   - SKILL.md with concise instructions\r\n   - Additional reference files if content exceeds 500 lines\r\n   - Utility scripts if deterministic operations needed\r\n\r\n3. **Review with user** - present draft and ask:\r\n   - Does this cover your use cases?\r\n   - Anything missing or unclear?\r\n   - Should any section be more/less detailed?\r\n\r\n## Skill Structure\r\n\r\n```\r\nskill-name/\r\n├── SKILL.md           # Main instructions (required)\r\n├── REFERENCE.md       # Detailed docs (if needed)\r\n├── EXAMPLES.md        # Usage examples (if needed)\r\n└── scripts/           # Utility scripts (if needed)\r\n    └── helper.js\r\n```\r\n\r\n## SKILL.md Template\r\n\r\n```md\r\n---\r\nname: skill-name\r\ndescription: Brief description of capability. Use when [specific triggers].\r\n---\r\n\r\n# Skill Name\r\n\r\n## Quick start\r\n\r\n[Minimal working example]\r\n\r\n## Workflows\r\n\r\n[Step-by-step processes with checklists for complex tasks]\r\n\r\n## Advanced features\r\n\r\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\r\n```\r\n\r\n## Description Requirements\r\n\r\nThe description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.\r\n\r\n**Goal**: Give your agent just enough info to know:\r\n\r\n1. What capability this skill provides\r\n2. When/why to trigger it (specific keywords, contexts, file types)\r\n\r\n**Format**:\r\n\r\n- Max 1024 chars\r\n- Write in third person\r\n- First sentence: what it does\r\n- Second sentence: \"Use when [specific triggers]\"\r\n\r\n**Good example**:\r\n\r\n```\r\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\r\n```\r\n\r\n**Bad example**:\r\n\r\n```\r\nHelps with documents.\r\n```\r\n\r\nThe bad example gives your agent no way to distinguish this from other document skills.\r\n\r\n## When to Add Scripts\r\n\r\nAdd utility scripts when:\r\n\r\n- Operation is deterministic (validation, formatting)\r\n- Same code would be generated repeatedly\r\n- Errors need explicit handling\r\n\r\nScripts save tokens and improve reliability vs generated code.\r\n\r\n## When to Split Files\r\n\r\nSplit into separate files when:\r\n\r\n- SKILL.md exceeds 100 lines\r\n- Content has distinct domains (finance vs sales schemas)\r\n- Advanced features are rarely needed\r\n\r\n## Review Checklist\r\n\r\nAfter drafting, verify:\r\n\r\n- [ ] Description includes triggers (\"Use when...\")\r\n- [ ] SKILL.md under 100 lines\r\n- [ ] No time-sensitive info\r\n- [ ] Consistent terminology\r\n- [ ] Concrete examples included\r\n- [ ] References one level deep\r\n\r\n## Tooling + Companions\r\n\r\nValidation tools + cs-* wrapper sit alongside this skill. Run all 6 review-checklist items programmatically:\r\n\r\n```\r\npython scripts/skill_review_checklist_runner.py path/to/skill-folder\r\n```\r\n\r\nSee [references/companion_tooling.md](references/companion_tooling.md) for the tool catalogue, cs-skill-author persona agent, and `/cs-write-a-skill` slash command.\r\n\r\n## When the knowledge is in a document, not your head\r\n\r\nThis skill authors from expertise you already have. When the source is a book, a docs folder,\r\na standard, or a pile of specs, use `engineering/book-to-skill` instead — it compiles the\r\ndocument into a knowledge-base skill (core frameworks + on-demand chapters + glossary +\r\npatterns + cheatsheet) and can package the result as a plugin.\r\n\r\n```\r\n/cs-book-to-skill <path|folder|glob> [skill-name]     # compile the source\r\n/cs-book-to-plugin <compiled-skill-dir>               # wrap it as a plugin\r\n```\r\n\r\nRule of thumb: **author first, compile second.** A hand-written skill states what you want the\r\nagent to do; a compiled book skill is the reference it consults while doing it. If you have\r\nboth, they are two skills, not one.\r\n\r\n---\r\n\r\n**Version:** 1.0.0\r\n**Derived:** Matt Pocock (MIT) + this repo's wrapper"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The write-a-skill/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/write-a-skill
  exported_at: "2026-11-03T07:42:36.469Z"