skill-authoring

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)

1. Metadata (name + description) — always in context. Keep it short.
2. SKILL.md body — loaded only when the skill triggers. Target under 300 lines. If you can't fit it, split.
3. 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:

1. Delete the offending guidance and see what happens. Fiddly overfit rules make skills worse over time.
2. Keep the prompt lean. Remove anything not pulling its weight.
3. 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

1. Draft the SKILL.md.
2. Come up with 2-3 realistic test prompts (the kind a user would actually type, with concrete file paths, casual phrasing, even typos).
3. Load the skill, give the model each test prompt, inspect.
4. Did the skill trigger? Did the output match? Did the model do a bunch of busywork?
5. 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.