Skip to content
Skills Library
AI & agents · Writing

write-a-skill

/write-a-skill

Creates a new agent skill with the right structure and bundled resources: a short SKILL.md, a trigger-rich description, reference files and scripts. Use when the user says things like: 'create me a skill', 'write a skill', 'new skill for', 'turn this workflow into a skill', 'write it the Pocock way'.

Repository
skills ↗
Licence
MIT
Last repository change
06.11.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
4
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

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

Licence

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

What it does and when to use it

Creates a new agent skill with the right structure and bundled resources: a short SKILL.md, a trigger-rich description, reference files and scripts. Use when the user says things like: 'create me a skill', 'write a skill', 'new skill for', 'turn this workflow into a skill', 'write it the Pocock way'.

Triggers from the description

create me a skillwrite a skillnew skill forturn this workflow into a skillwrite it the Pocock way
Original author description

Creates a new agent skill with the right structure and bundled resources: a short SKILL.md, a trigger-rich description, reference files and scripts. Use when the user says things like: 'create me a skill', 'write a skill', 'new skill for', 'turn this workflow into a skill', 'write it the Pocock way'.

How it works

  1. Process
  2. Skill Structure
  3. SKILL.md Template
  4. Description Requirements
  5. Who can invoke it (Claude Code frontmatter)
  6. When to Add Scripts
  7. When to Split Files
  8. Review Checklist
Original SKILL.md headings · 143 lines, 793 words
SKILL.md preview
---
name: write-a-skill
description: "Creates a new agent skill with the right structure and bundled resources: a short SKILL.md, a trigger-rich description, reference files and scripts. Use when the user says things like: 'create me a skill', 'write a skill', 'new skill for', 'turn this workflow into a skill', 'write it the Pocock way'."
---

# Writing Skills

Read [HOUSE-RULES.md](HOUSE-RULES.md) in this folder before you draft. It holds the rules that came
from real incidents. This file is the method. That file is the list of mistakes to avoid.

## Process

0. **Check for an existing skill first.** List the installed skills (`ls ~/.claude/skills/` and the
   project's `.claude/skills/`). Before you draft, say in your first reply which existing skill is
   closest (name it) and pick one: (a) it already does the job, so use it; (b) extend it, so the new
   text goes into that skill (long parts in its `references/` folder); (c) truly new, with one line on
   why no existing skill fits. Do not answer from memory. Look at the real list.

1. **Gather requirements.** Ask the user:
   - What task or domain does the skill cover?
   - What specific use cases should it handle?
   - Does it need executable scripts, or only instructions?
   - Are there reference materials to include?

2. **Draft the skill.** Create:
   - `SKILL.md` with concise instructions
   - Extra reference files once `SKILL.md` would pass about 100 lines
   - Utility scripts if a step is deterministic

3. **Review with the user.** Present the draft and ask:
   - Does this cover your use cases?
   - Is anything missing or unclear?
   - Should any section have more or less detail?

4. **Install** only after the user says yes: put the folder in `~/.claude/skills/<name>/` (for all
   projects) or `<project>/.claude/skills/<name>/` (for one project).

5. **Try it once** on a real request before you say it works.

## 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 (plus the optional `when_to_use` field) is what your agent reads to decide which
skill to load. It sits in the system prompt next to every other installed skill. Claude Code gives all
skill listings about 1% of the context window. When that is full, descriptions are dropped (least
used first) and only the name stays. So keep it short and put the trigger words early.
(Checked 2026-10-19: https://code.claude.com/docs/en/skills)

**Goal:** give your agent just enough to know:

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

**Format:**

- Max 1024 characters (the portable Agent Skills limit). Claude Code also cuts the description plus `when_to_use` at 1,536 characters per skill in its listing (same URL).
- Write in third person.
- First sentence: what it does.
- Second sentence: "Use when [specific triggers]". Use the exact phrases people really say.

**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 tell this skill from other document skills.

## Who can invoke it (Claude Code frontmatter)

- Default: the user and Claude can both invoke it.
- `disable-model-invocation: true`: only the user can start it (`/name`). The description leaves Claude's context. Use it for skills with side effects (deploy, publish, spend).
- `user-invocable: false`: hidden from `/`. Only Claude loads it. Use it for background knowledge.
- Claude-only keys such as `context: fork` and `effort` are not portable to other agents. Leave them out of skills meant for other tools.
(Checked 2026-10-19: https://code.claude.com/docs/en/skills)

## When to Add Scripts

Add utility scripts when:

- The operation is deterministic (validation, formatting)
- The same code would be generated again and again
- Errors need explicit handling

Scripts save tokens and are more reliable than code written fresh each time.

## When to Split Files

Split into separate files when:

- `SKILL.md` passes 100 lines (a house rule; Claude Code's own advice is under 500 lines)
- The content has distinct domains (finance vs sales schemas)
- Advanced features are rarely needed

## Review Checklist

After drafting, check:

- [ ] The description includes triggers ("Use when...")
- [ ] `SKILL.md` is under 100 lines
- [ ] No time-sensitive info
- [ ] Consistent terminology
- [ ] Concrete examples included
- [ ] References are one level deep
- [ ] Closest existing skill named, and "extend or new" decided
- [ ] Every path and skill name in the text really exists (`ls` it)
- [ ] The rules in HOUSE-RULES.md are applied
Files in this package (4)
  • HOUSE-RULES.md 3 KB
  • LICENSE 1 KB
  • README.md 2 KB
  • SKILL.md 5 KB

Versions

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

Database snapshot: 13.11.2026 · package version 973ffd948d8a (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

  • 90skill-author
    Use when an author needs to create, review, audit, or improve an Agent Skill and its supporting references or scripts.
  • 100write-project-skill
    Create global or project-local agent skills with concise SKILL.md files, progressive disclosure, and optional deterministic scripts. Use when the user wants new skills for a project, workspace, domain, or global AI setup.
  • 100skill-authoring
    Write a new agent skill or improve an existing one, as a folder with a SKILL.md file and optional scripts. Use when the user asks to create a skill, turn a repeated workflow or set of instructions into a skill, or fix a skill that an agent does not pick up or follows badly.
  • 100skill-creator
    Create, improve, and evaluate agent skills (SKILL.md plus reference files). Use this skill whenever the user wants to build, scaffold, or design a new skill, improve or fix an existing skill that isn't working well, score or benchmark a skill's quality or run evals on it, or…
  • 100write-skill
    Write, improve or test a Blueprint skill (a SKILL.md whose description makes the agent load it at the right moment and whose body says why), and check it with and without the skill. Use it to turn a way of working into a skill, or when a skill is not used or used at the wrong time.
  • 100write-skill
    Create a new agent skill, or improve an existing one, inside this skills repo, following its housekeeping rules. Use when asked to "write a skill", "make this a skill", "save this as a skill", "turn what we just did into a skill", or "improve the X skill".

Feedback and reports

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