# Skill Creating

> Author or revise an Agent Skill, a subagent or agent role file, or a lifecycle hook with progressive disclosure. Use when creating or editing a SKILL.md, writing its description or frontmatter, designing the slim body, or scaffolding a new skill. Also use when a skill is over budget, prompts are bloated, or an agent keeps missing a step or ignoring instructions.

- Skill: `zalom/skill-creating` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add zalom/skill-creating`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zalom/skill-creating/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: zalom (https://skillmd.com/u/zalom)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zalom/skill-creating

---


# Creating Skills

Author skills, agents, and hooks as thin routers over deep references. This
body carries the rules that must stay correct without opening anything, then
routes each authoring task to the reference that holds the depth.

## Rules (must be right even if no reference is opened)

- Three load levels, hard budgets: metadata around 100 tokens (always loaded),
  body under 5000 tokens and under 500 lines (loaded on trigger), references on
  demand. Keep the body well under budget, not at the ceiling.
- Progressive disclosure first: the body routes, the references hold the depth.
  Any deep how-to in the body belongs in a reference instead.
- Description states WHEN to use, not the workflow. Write it in third person,
  front-load concrete trigger keywords, and include at least one indirect
  trigger (a request that never names the domain). Never summarize the steps.
- Bind every reference link to an observable trigger condition. Never leave a
  bare pointer to a reference.
- References stay one level deep. Any reference over 100 lines opens with a
  table of contents.
- Build at least three evals before writing extensive docs.
- Match determinism to fragility: a deterministic script for fragile or
  repeated mechanical steps, prose for judgment calls.
- Imperative voice, no second person. Never use em dashes or en dashes in
  user-facing docs or newly authored skill text; use commas, periods,
  parentheses, or colons.

## Route the authoring task to its reference

| Authoring task | Open |
|---|---|
| Starting any authoring task: load the load-level model and the thin-router pattern first | `references/progressive-disclosure.md` |
| Authoring an Agent Skill (frontmatter, description, slim body, voice) | `references/skills.md` |
| Authoring a subagent or Agent role file | `references/agents.md` |
| Authoring a lifecycle hook | `references/hooks.md` |
| Deciding script versus prose, or writing a script | `references/scripts.md` |
| Building evals for a skill | `references/evals.md` |
| Naming an external skill as a default or dependency | `references/progressive-disclosure.md` (Optional dependencies) |

## Shrink context, or let a skill self-improve

- When prompts or tool output blow the context budget, open `references/hooks.md` (E7) for
  the global token levers: a PostToolUse hook that trims noisy tool output before it enters
  context, and Programmatic Tool Calling that keeps looped tool results in code, not context.
- When a skill should learn from its own real runs, open `references/hooks.md` (E8) for the
  propose-only Stop or SubagentStop loop (transcript to proposed edits to human approval to
  git, effort-gated). The dedicated skill is the future `improving-skills` skill.

## Scaffolder and evals

- To start a new skill, agent, or hook from a born-slim file, run
  `scripts/scaffold.rb`.
- To design, run, and grade evals in depth (paired runs, assertions after
  observing, pass rates), use the `skill-evaluating` skill.