Skillify authoring

Skillify authoring is the practice of writing a skill as a folder that loads only when needed. A skill is a folder, not one file loaded every time; the folder holds SKILL.md, scripts, references, and assets.¹

Overview#

SKILL.md is the default read and states when to load the skill plus its constraints.¹ Heavy docs stay in references and load only when needed.¹ Editorial note: a language model may draft a skill or its evals; a human edits and signs it, and nothing ships unedited (see Contradictions).

Mechanism#

1. A short load-when description is written in the words people say when something is wrong.¹
2. The body is kept to constraints the agent would get wrong, and it points at references.¹
3. Deterministic work goes in scripts.¹
4. Should-trigger and should-not-trigger checks are written before the skill.¹
5. On failure, a gotcha is appended.¹ Editorial note: a skill is rewritten only from real runs (see Contradictions).
6. The skill is registered so that it is reachable, and one real task is done before the work is turned into a skill.²

Applications#

The practice applies when a repeated workflow should compound as a skill instead of a longer prompt.

Limitations#

A skill that nothing can trigger is not useful, which is why registration matters.² A single always-loaded file is the opposite of the pattern. Editorial note: a skill shipped by the model alone, without human editing, is excluded (see Contradictions).

Worked example#

The playbook in the source article has five steps.¹

1. Before the skill is written, ten queries that should trigger it and ten that should not are written. If they cannot be written, the skill is not needed.
2. The description is written as a router that starts with “Load when” and uses the words people say when something is wrong, such as “my build is broken”, not capability wording such as “compilation error resolution”.
3. SKILL.md is kept to constraints the agent would get wrong without them. Deterministic code goes in scripts/, heavy docs in references/, and templates and schemas in assets/, and the body points at them.
4. When the skill fails, a gotcha is appended instead of the description or body being rewritten. A change that breaks more than two of the trigger checks is reverted.
5. The human who watched the agent fail writes the skill; a model-generated scaffold is a draft, not a release.

See also#

• Thin harness, fat skills – latent versus deterministic work, and agent-native command lines under skills
• Agentic foundations – scripting what repeats
• GBrain – a tool note
• Obsidian agent skills – a skill pack example
• Loop engineering – scheduled orchestration

Further reading#

• https://x.com/nicolascole77/status/2049829813561749947
• https://x.com/garrytan/status/2046876981711769720
• https://x.com/garrytan/status/2044479509874020852
• https://x.com/av1dlive/status/2058951175236727025

References#

Footnotes#

1. https://x.com/av1dlive/status/2053880492680958439 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹

2. https://x.com/garrytan/status/2053127519872614419 ↩ ↩²