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

create-skill

/create-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.

Licence
MIT
Last repository change
24.10.2026

Assessment and security

90/ 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.
Content25 / 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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.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

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.

Triggers from the description

make a skill for X
Original author description

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.

How it works

  1. Layout
  2. Body shape
  3. Frontmatter
  4. Description
  5. Writing style
  6. Failure modes
  7. Checklist
Original SKILL.md headings · 71 lines, 883 words
SKILL.md preview
---
name: create-skill
description: 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.
---

# Creating Skills

Read 1–2 neighboring skills first to match conventions. Draft `SKILL.md`, review it with the user against the checklist at the end.

## Layout

`skill-name/SKILL.md` is the entry point and the only required file. Push long-form docs to `references/<topic>.md` (linked, loaded on demand), deterministic helpers to `scripts/`, output templates to `assets/`. Split when `SKILL.md` passes ~150 lines or content has distinct domains (e.g. one variant per reference file so the agent loads only the relevant one).

Three disclosure levels: `name` + `description` (always in context — the sole routing signal) → `SKILL.md` body (loaded on trigger) → bundled resources (loaded on demand).

## Body shape

A body is **steps** (ordered actions), **reference** (rules and definitions consulted on demand), or both — let the content pick the shape. Don't force `Workflow` / `Rules` / `Error Handling` headings onto a skill that doesn't need them; empty scaffolding is a no-op.

Every step ends on a **completion criterion** the agent can check ("every error path returns a typed result", not "handle the errors") and that is exhaustive where it matters ("every modified file has a test"). A vague criterion invites premature completion.

## Frontmatter

| Field | Notes |
|---|---|
| `name` | kebab-case, matches directory. No version suffixes — evolve in place |
| `description` | The only routing signal for a model-invoked skill (see below) |
| `argument-hint` | Shown next to the name, e.g. `'[slug]'`, `'<idea>'` |
| `disable-model-invocation` | `true` = user-invoked only; the description becomes a one-sentence human summary |
| `user-invocable` | `false` = model only; hidden from the `/` menu, reached by other skills or plain phrasing |
| `effort` | `low` / `medium` / `high` / `xhigh` / `max` for the turn the skill fires; set only when it deviates from the `medium` default |
| `allowed-tools` | Tools pre-approved for the invoking turn — use sparingly |

Effort routing: `low` for mechanical single-place edits (`commit`, `to-adr`); `high` for multi-file features, unknown-cause debugging, review (`build`, `debug`); `xhigh` for architecture, migrations, security-sensitive work (`architecture-audit`, `harden`).

## Description

Third person, ≤ ~350 chars, three sentences: what it does; `Use when [triggers]`; `Don't use for [anti-triggers]` pointing at neighbor skills. The agent picks among every installed skill's description — vague phrasing ("helps with documents") gives it nothing to distinguish.

Triggers are how users actually talk (phrases, file types, contexts), not the slash name — `/name` always works and costs tokens in the description. Claude under-triggers more than it over-triggers: if a useful skill rarely fires, make the trigger clause more generous.

Description anti-triggers are the one place negation earns its keep — `Don't use for X` routes correctly.

## Writing style

- Imperative form (`Run X`, not `You should run X`). Explain the why instead of stacking `ALWAYS`/`NEVER` in caps; one `MUST` for a hard constraint is fine, a wall of caps is a yellow flag.
- **Leading words**: anchor behavior with compact pretrained concepts (`tight`, `red`, `deep`, `surgical`) reused across the skill. One word carries distributed meaning and doubles as a trigger when it appears in prompts or code. Strengthen a weak word rather than piling on rules.
- **No-op test**: delete any sentence that doesn't change the model's default behavior. Prefer deletion to rewriting.
- **Prompt the positive**: state the target behavior — "don't think of an elephant" names the elephant. Keep a prohibition only as a hard guardrail you can't phrase positively, paired with what to do instead.

## Failure modes

Diagnose a misbehaving skill against these:

- **Premature completion** — a step ends before it's done. Sharpen the completion criterion first; only if irreducibly fuzzy *and* you see the rush, split later steps out of view.
- **Duplication** — the same meaning in two places. Keep one source of truth.
- **Sediment** — stale layers that accumulate because adding feels safe and removing feels risky.
- **Sprawl** — too long even when every line is live. Push reference into `references/`, split by variant.
- **No-op** — a line the model already obeys. Delete it. A weak leading word (`be thorough`) is a no-op; the fix is a stronger word (`relentless`).
- **Negation** — steering by prohibition; see Prompt the positive.

## Checklist

- [ ] Folder name matches `name:`
- [ ] Description: model-invoked → what / use when / don't use; user-invoked → one sentence
- [ ] Body shape fits the content; every step has a checkable completion criterion
- [ ] `effort` set only when it deviates from `medium`
- [ ] Tier frontmatter follows the tier rule in `docs/skill-conventions.md`; a typed-only skill ends on a filled-in `Next: /hb:<cmd> <args>` line, the only place it names another typed-only skill
- [ ] `SKILL.md` under ~150 lines
- [ ] Text other people wrote is called data where it's fetched and in every subagent brief (`docs/skill-conventions.md`)
- [ ] Every git or shell command ran in a scratch repo, deletions and renames included
- [ ] Calls to another skill say "Call the Skill tool with `<skill-name>`" (one skill per call); user-facing suggestions say `/hb:<cmd>`, description hints keep `/<skill-name>`; no `../` links across skill folders
- [ ] Added to README, the `AGENTS.md` intent → skill mapping, and `guide`'s map; no existing skill already covers it
- [ ] `.claude-plugin/plugin.json` `version` bumped (semver)

Versions

RepositoryScoreLicence
This page · helderberto/agent-skills90MIT
mgiovani/cc-arsenal100MIT
zylos-ai/zylos-core100MIT
mthines/agent-skills100MIT
jongio/skills100MIT
fairladyz625/harness-anything100AGPL-3.0
coco-research/coco100MIT
builderio/agent-native100MIT
BrandeisPatrick/silo-harness100MIT

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

  • 100skill-creator
    A meta-skill for creating Markdown skills. Handles SKILL.md frontmatter and body, Progressive Disclosure, and the create_skill procedure. Use when: Use when: adding new skills, checking description rules for read_memory_file, or generating skills with references or templates.
  • 100skill-creator
    How to create new skills for this HQ — format, frontmatter, content structure. Use when you need to add a new skill to this repository, or when reviewing whether an existing skill is well-formed.
  • 100skills-best-practices
    Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger.
  • 100skill-creator
    Markdownスキルを作成するメタスキル。SKILL.mdのfrontmatterと本文、Progressive Disclosureとcreate_skillの手順を扱う。 Use when: 新規スキル追加、read_memory_file 向けの記述ルール確認、referencesやtemplates付きスキル生成が必要なとき。
  • 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.
  • 100skill-creator
    Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

Feedback and reports

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