# Write Skills

Create or revise agent skills.

- Repository: https://github.com/dzhng/skills (1394 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dzhng/skills --skill write-skills -g -a claude-code -y`
Codex: `npx skills add dzhng/skills --skill write-skills -g -a codex -y`
Cursor: `npx skills add dzhng/skills --skill write-skills -g -a cursor -y`
Gemini CLI: `npx skills add dzhng/skills --skill write-skills -g -a gemini-cli -y`

## Description

Create or revise agent skills. Use when adding a new skill file, renaming a skill, simplifying an existing skill, improving trigger descriptions, or deciding what belongs in a skill versus references, scripts, assets, or ordinary docs.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Write Skills

A skill is not documentation. It is compressed operational memory for an
agent that already knows how to code and reason. Its job is
**predictability**, the agent taking the same *process* every run, not
producing the same output. Put only the context that changes what the agent
will do.

## First Principles

1. **Trigger from the description.** The frontmatter `description` is the
   only part read before the skill loads. Say what the skill does and the
   concrete situations that should trigger it. Do not hide trigger rules in
   the body.

2. **Spend tokens like they are scarce.** Assume the agent is already good at
   general reasoning. State the direction and let smart models figure out
   implementation details. A wrapper skill can be two sentences: name the
   capability to use and the skill to follow. Add mechanics only when a
   demonstrated failure requires them.

3. **Write procedures, not essays.** Prefer imperative rules, decision
   points, and small examples. A good skill changes behavior in the next
   turn; it does not merely explain the topic. And match the procedure to
   the deliverable's shape: a catalog of techniques with "pick what fits"
   produces tool-picking, not a flow, if the job is a shaped interaction
   (an interview, a staged walk), the workflow must *be* that shape, with
   the techniques demoted to steps inside it.

4. **Use progressive disclosure.** Keep the main skill file short. Push long
   schemas, examples, provider docs, or variant-specific guidance out into
   linked `references/` files, reached by a pointer that fires only when
   needed. Put repeatable fragile operations in `scripts/`. Put reusable
   output material in `assets/`.

The rest: https://github.com/dzhng/skills/blob/HEAD/skills/authoring/write-skills/SKILL.md