skill-creator

Files (3)

• SKILL.md
• openai.yaml · agents/
• GLOSSARY.md · resources/manual/

SKILL.md (first lines)

# Skill Creator

A skill exists to wrangle determinism out of a stochastic system. **Predictability** - the agent taking the same _process_ every run, not producing the same output - is the root virtue; every convention below serves it. Write the skill so the next run behaves like the last one.

**Bold terms** are defined in [`GLOSSARY.md`](resources/manual/GLOSSARY.md); look them up there for the full meaning.

## Where a skill lives

Every skill is a directory holding a `SKILL.md`, placed by what it does:

```text
skills/<category>/<name>/SKILL.md
```

- **`<category>`** is one of the ten topic buckets: `engineering`, `game-development`, `planning`, `review`, `github`, `reflection`, `writing`, `authoring`, `tooling`, `tars`. Category comes from the directory - never from a frontmatter key.
- One **lifecycle bucket** sits inside the tree: `in-progress/` holds drafts. Retired skills leave `skills/` entirely for the top-level **archive**, `skills-archive/<category>/<name>/`, which keeps the original category.

**Promotion** is the payoff of living in a topic bucket: only skills under the ten categories appear in the generated README, index, and installer. A skill in `in-progress/` is deliberately excluded - move it into a topic bucket to promote it. To retire one, use `/skill-archive`, which moves it to `skills-archive/` where it stays readable on the dashboard but is never installed.

## Naming

The name is prefix-free kebab-case, and it must equal the directory basename (`skills/writing/proofread/` is named `proofread`).

- **Verb-first for an action** the skill performs (`sculpt-code`, `git-resolve-conflicts`); **a noun for a body of knowledge** it holds (`tdd`, `agent-guidelines`).
- **Keep only a genuine subject scope** as a prefix - `gh-` for GitHub API work, `git-` for git operations. These name a real tool the skill acts on; a project or subsystem name is a genuine scope too (`acme-` for skills that only make sense inside the Acme tool, so `acme-deploy` is correct). Drop taxonomy prefixes like `cmd-`, `brain-`, or `sys-`; the category directory already carries that signal.
- 1 to 64 characters matching `^[a-z0-9]+(-[a-z0-9]+)*$`, and it must not contain "anthropic" or "claude".

## Canonical frontmatter

The minimum is two keys:

```yaml
---
name: kebab-case-name
description: What the skill does AND when to reach for it, in the user's own words.
---
```

`name` matches the directory (1 to 64 characters). `description` is **model-facing** and does the invocation work (1 to 1024 characters, see below). Optional keys, each added only when earned:

- **`disable-model-invocation: true`** - requests explicit invocation in hosts that support this field (see below).
- **`argument-hint`** - a short usage hint for a skill that takes an argument.
- **`context: fork`** with **`agent: <type>`** (used together, e.g. `agent: general-purpose`) - runs the skill as a subagent in its own context, so a long or noisy run does not silt up the caller's window.
- **`metadata:`** - a flat string→string map for provenance and grouping. Use `source` and `license` on any skill adapted from an outside project (as this one carries `source: mattpocock/skills`, `license: MIT`). Use `group: <group-name>` to declare membership in a cohesive cross-reference group (standard groups: `authoring`, `github`, `planning-pipeline`, `review`, `opencode`, `tars`, `nutanix`). Skills are self-contained by default; cross-references via `/skill-name` mentions or relative markdown links are only permitted between skills in the same group (`skill-router` is exempt).
- **`resources:`** - a YAML **list** of source URLs. It is functional, not decorative: `ask skills download-resources` reads it (implemented in `crates/skills-core/src/downloader.rs`) to (re)fetch vendored docs into the skill's `resources/auto/` directory (see the structure rule below), and reference skills rely on it. Keep it intact; never strip it.

That is the complete allowed set, so the frontmatter stays small. Every promoted custom skill also requires an `agents/openai.yaml` sidecar with an explicit invocation policy. These authoring requirements exclude vendor snapshots and archived skills. Distinct from the above are the **legacy** keys `custom:`, `triggers:`, `category:`, and `type:` - forbidden. Earlier skills carry them mid-migration; a new or edited skill drops them, putting triggers into the `description` prose and taking the category from the directory. Do not confuse these forbidden legacy keys with the real, functional `resources:` and `metadata:` keys above.

## Invocation

Choose how the skill should be selected, then encode the same choice for Claude Code and Codex:

- **Automatic**: focused references and bounded task helpers that the agent needs during an authorized task. Omit `disable-model-invocation` or set it to `false`, and set `policy.allow_implicit_invocation: true` in `agents/openai.yaml`.
- **Explicit only**: publishing, lifecycle operations, large orchestration workflows, and catalogs intended for deliberate user initiation. Set `disable-model-invocation: true` and `policy.allow_implicit_invocation: false`.

Judge the entry point and its role, not just its length or interactivity. A design interview helper such as `grilling` can remain automatic for an explicitly requested design interview or a bounded interview step required by an authorized parent workflow. Likewise, `git-resolve-conflicts` can remain automatic when an authorized Git operation encounters conflicts. Give each a narrow description that names that trigger.

Automatic selection loads guidance; it does not authorize publishing, deletion, messages, or other actions. Follow the user's authorized scope and the skill's action gates after loading it.

Enforcement varies by host. Claude Code supports `disable-model-invocation`; Codex uses its sidecar policy; OpenCode V2 supports the Claude field as an alias. OpenCode 1 and the inspected native Goose loader do not enforce it. Antigravity has no documented equivalent for disabling implicit selection; its CLI `disable-slash-command` field hides explicit slash invocation while keeping model invocation available. See [provider evidence and limitations](resources/manual/invocation-compatibility.md) when choosing host-specific controls.

For explicit-only skills, keep the trigger in the shared description and add this standing instruction near the start of the body:

```text
Use this skill only when the user explicitly requests its workflow.
```

On hosts without an invocation control, that instruction and the description are advisory guidance, not an enforced restriction. Do not promise universal zero context cost, removal from every model's catalog, or that other workflows can never reach the skill.

## Writing the description

A shared **description** tells the model what the skill does and when it applies. All supported hosts use it for discovery, subject to their invocation controls and catalog budgets. Codex's `interface.short_description` is separate user-facing UI text and does not replace it.

Write one or two sentences, usually aiming for 100-220 characters. This is an editing guideline, not a new validation ceiling. Name the capability and its concrete trigger; include a boundary only when it resolves a likely ambiguity. Explicit-only skills should say that the user must request the workflow.

```yaml
description: Explain repository module boundaries and interface tradeoffs. Use when designing a module or reviewing where an abstraction should live.
```

- **Front-load the capability and main trigger.** Hosts may shorten descriptions when many skills are installed.
- **Avoid keyword inventories.** Collapse synonyms and feature lists into the task the user is trying to complete.
- **Keep the boundary concrete.** Distinguish adjacent workflows by their inputs or intended result; keep implementation detail in the body.
- **No frontmatter slop or puffery.** Never begin descriptions with "This skill provides...", "Expert guidance for...", "Expert reference...", or "Comprehensive guide...". Lead immediately with the capability verb phrase (e.g. `Build...`, `Audit...`, `Deploy...`). Avoid buzzwords like "comprehensive", "robust", or "seamless". `ask skills lint` checks for these forbidden patterns.
- **No em-dashes.** Never use em-dashes (Unicode U+2014) in skill names, frontmatter descriptions, or skill bodies; use standard hyphens (`-`), colons, commas, or restructure sentences. `ask skills lint --fix` can automatically sanitize em-dashes.

## Structure and progressive disclosure

A skill's content is ranked by how immediately the agent needs it - the **information hierarchy**, a ladder with three rungs:

1. **In-skill step** - an ordered action in `SKILL.md`: what the agent does, in order. The primary tier.
2. **In-skill reference** - a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a flat peer-set (every rule of a review on one rung), which is a fine arrangement, not a smell.
3. **External reference** - reference pushed out of `SKILL.md` into a sibling file, reached by a **context pointer** and loaded only when the pointer fires (this skill discloses its definitions to `GLOSSARY.md`).

**Progressive disclosure** is the move down the ladder - out of `SKILL.md` into a linked file - so the top stays legible. Siblings live beside `SKILL.md` under `resources/`, which splits by ownership:

```text
skills/<category>/<name>/
  SKILL.md          # entry point - steps and top-tier reference
  agents/           # required for promoted custom skills
    openai.yaml     # OpenAI Codex / ChatGPT app UI metadata and policy
  resources/        # optional; holds ONLY these two subdirectories:
    auto/           # downloader-owned - (re)fetched from the `resources:` URLs; never hand-edit
    manual/         # hand-authored scripts, docs, references, and static files
```

Never place a file directly in `resources/`: every resource lives under `auto/` (managed by `ask skills download-resources`, safe to wipe and reproduce) or `manual/` (yours, tooling never touches it). `ask skills lint` enforces this, and `ask skills clean-resources` deletes only `auto/`.

**Markdown and Linking Rules**:

- **Code fence language tags (MD040)**: Never use bare triple backticks. Always declare a language tag (` ```bash `, ` ```json `, ` ```text `, ` ```rust `).
- **Blank lines around fences (MD031)**: Every code block must be preceded and followed by a blank line, including when nested inside lists.
- **No absolute file links**: Never use `file:///` URLs referencing local paths. Always use relative repository paths (e.g. `../../review/code-review/SKILL.md`).
- **Heading formatting**: Headings must use plain text sentence case without bold markup (e.g. `### 1. Audit environment`, never `### 1. **Phase 1: Initial Assessment**`). Bold markup inside headings is prohibited and flagged by `ask skills lint`.
- **No tautological list items**: Never use bold list lead-ins that merely repeat the item name (e.g. `- **Performance:** Optimize performance...`). State concrete details or use direct prose.

**Branching** is the disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A pointer's _wording_, not its target, decides when and how reliably the agent follows it - a must-have behind a weak pointer is a variance bug, so sharpen the wording before pulling material back inline.

## Completion criteria

From MAHDTech/agent-skills, MIT.

More from MAHDTech/agent-skills