| name | skill-authoring |
| description | How to author a ZCode SKILL.md that triggers reliably and stays lean. The format, the description discipline (route-by-intent, not keywords), progressive disclosure (metadata → body → bundled files), and the anti-over-build stance (delete guidance that isn't pulling its weight). ROUTE BY INTENT — load when writing a new skill, revising an existing one, turning a repeated workflow into a skill, or debugging why a skill doesn't trigger. NOT for authoring plugins/hooks (those are separate). |
Skill authoring — write SKILL.md that triggers and stays lean
A skill is a directory with a SKILL.md. ZCode discovers it, and when the user's intent matches the description, the body loads. The hard parts are: writing a description that triggers reliably without devolving into keyword stuffing, and keeping the body lean enough that it helps rather than over-prescribes.
The frontmatter
---
name: <kebab-case, matches the directory name>
description: >-
<one paragraph: WHAT it does + WHEN to load it, routed by intent not keywords>
---
name — lowercase kebab-case, 1-64 chars, MUST match the directory name exactly.description — the only trigger signal ZCode always has in context. Write it for intent, not keywords:
- Bad (keyword-stuffed): "Triggers on 'design review', 'UX check', 'WCAG audit', '이 화면 어때', 'craft 점검'..."
- Good (intent-described): "JUDGE whether a rendered UI is good enough to ship. Load when the intent is to evaluate quality — including indirect signals like dissatisfaction, hesitation, or a ship/no-ship moment."
- Optional:
model (claude-specific: haiku/sonnet/opus/inherit — not GLM-relevant).
Progressive disclosure (three layers)
- Metadata (name + description) — always in context. Keep it short.
- SKILL.md body — loaded only when the skill triggers. Target under 300 lines. If you can't fit it, split.
- Bundled files (
references/, scripts/, assets/) — read on demand. Unlimited size.
If the body is long, split domain detail into references/<topic>.md and have the SKILL.md point to it: "if the target is X, read references/X.md before proceeding."
The description discipline (route by intent)
Models under-trigger skills. The fix is NOT to list more keywords — it's to describe the intent and its indirect signals:
| Pattern | Example |
|---|
| Name the verb (JUDGE / PRODUCE / CONVERGE / DETECT / VERIFY) | "JUDGE whether a rendered UI is good enough to ship" |
| List direct signals (the obvious phrases) | "'review', 'how is it?', '검토'" |
| List indirect signals (the subtle ones) | "dissatisfaction, hesitation, silence after a screenshot, a ship/no-ship moment" |
| Name what it is NOT | "NOT for designing new (that's ux-design-baseline)" |
The indirect signals are what catch the user's real phrasing. "음..." after a shared screenshot won't match any keyword, but it WILL match "silence after a screenshot" if that's in the description.
Writing style
- Imperative form ("Read the file before editing", not "You should read the file...").
- Explain why when the rule isn't obvious. Models follow guidance better when they understand the reason.
- Examples beat rules. If the skill produces structured output, include a literal example of the format.
- Avoid all-caps MUST/NEVER unless absolutely critical. If you find yourself shouting, the rule probably needs better explanation, not louder enforcement.
The anti-over-build stance
The most common failure mode: a skill that over-prescribes and creates busywork (re-reading files, writing throwaway scripts, going in circles). When a skill causes busywork:
- Delete the offending guidance and see what happens. Fiddly overfit rules make skills worse over time.
- Keep the prompt lean. Remove anything not pulling its weight.
- Generalize from feedback. You're iterating on a few examples for speed, but the skill needs to work for inputs neither of you has seen. A stubborn issue → try a different framing, not more constraints.
Authoring loop
- Draft the SKILL.md.
- Come up with 2-3 realistic test prompts (the kind a user would actually type, with concrete file paths, casual phrasing, even typos).
- Load the skill, give the model each test prompt, inspect.
- Did the skill trigger? Did the output match? Did the model do a bunch of busywork?
- Improve: apply → re-test → repeat until the output lands or improvements stop landing.
A skill that doesn't trigger is invisible. A skill that over-prescribes is harmful. The goal is a skill that triggers on the right intent and then gets out of the way.
