Skip to content
Skills Library
AI & agents · Building & coding

write-a-skill

/write-a-skill

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.

Licence
MIT
Last repository change
30.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
3
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 30.06.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/skill_description_validator.py, scripts/skill_review_checklist_runner.py, scripts/skill_structure_validator.py

What it does and when to use it

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.

Original author 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.

How it works

  1. Process
  2. Skill Structure
  3. SKILL.md Template
  4. Description Requirements
  5. When to Add Scripts
  6. When to Split Files
  7. Review Checklist
  8. Tooling + Companions
Original SKILL.md headings · 131 lines, 507 words
SKILL.md preview
---
name: write-a-skill
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.
license: MIT
metadata:
  derived_from: "https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill"
  original_author: "Matt Pocock (@mattpocock)"
  original_license: MIT
  voice: "Matt Pocock — direct, concrete, imperative, example-driven"
  version: 1.0.0
---

# 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.

---

**Version:** 1.0.0
**Derived:** Matt Pocock (MIT) + this repo's wrapper
Files in this package (9)
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB
  • references/companion_tooling.md 4 KB
  • references/description_design_patterns.md 6 KB
  • references/progressive_disclosure_principles.md 5 KB
  • references/quality_gates_for_skills.md 9 KB
  • scripts/skill_description_validator.py 9 KB
  • scripts/skill_review_checklist_runner.py 9 KB
  • scripts/skill_structure_validator.py 10 KB

Versions

RepositoryScoreLicence
This page · bestagentkits/agency-skills100MIT
borghei/Claude-Skills100MIT
alirezarezvani/claude-skills100MIT
redpanda-data/ui-harness100MIT
RubenGlez/rubstack100MIT
holl4ndtv/skills100MIT
yamcodes/arkenv100MIT
mkurman/zorai100MIT
AmirAzy/HoNspot100MIT

Database snapshot: 13.11.2026 · package version 49f33d1f4354 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95skill-creator
    This skill should be used when the user wants to "add a skill", "create a skill", "make a new skill", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices.…
  • 100fai-skill-template
    Create SKILL.md files following the Agent Skills specification with proper frontmatter, structured content, and progressive disclosure. Use when authoring new skills for VS Code Copilot, Claude, or other agent platforms.
  • 100claude-skills
    Guide for creating Agent Skills with progressive disclosure and best practices. Use when creating new skills, understanding skill structure, or implementing progressive disclosure.
  • 95skill-development
    This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.
  • 100add-skill
    Create new Claude Code skills with proper structure. Use when adding a skill or slash command.
  • 90create-skill
    Create or restructure agent skills — frontmatter, description routing, progressive disclosure. Use when asked to create, write, or build a new skill, or "make a skill for X". Don't use for eval-driven trigger optimization (skill-creator) or one-off prose edits to a skill.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.