9 Principles That Separate Useful Skills From Markdown Essays
A skill can be beautifully written and still fail in three different moments:
These nine principles follow that lifecycle—from selection, through execution, to contact with reality.
Act 1: Getting selected
At session start, the model does not read every SKILL.md. It sees the skill listing: mainly the name and description.
The description is therefore not a summary. It is the primary selection signal. Say what the skill does, which requests should trigger it, and what nearby work should not.
If a skill loses the metadata-only round, nothing inside the body can rescue it.
Context is a shared budget. Every token spent on one skill competes with the conversation, project context, and other capabilities.
Load information in layers:
Assume the model already knows general concepts. Spend tokens on your workflow, constraints, examples, and domain-specific gotchas.
A long essay about good testing can be read, summarized, and ignored. A workflow with checkpoints changes what the agent actually does.
If a competent junior engineer could not tell what to do next, the file is reference material—not a skill. Steps with exit criteria beat advice without them.
Act 2: Running reliably
Strings of ALWAYS, NEVER, and MUST encourage literal compliance without judgment. State the rule, then state its reason.
The reason becomes a rubric when the model encounters an edge case you did not anticipate. It also helps distinguish a real invariant from a preference.
Even when a rule and its rationale are clear, a capable model may rationalize skipping it: the change is small, the user is in a hurry, the expensive validation probably is not needed this time.
For non-negotiable steps, document the common shortcut explicitly and rebut it. If the same rationalization appears in repeated runs, turn that observation into a guardrail.
Do not ask the model to recreate the same validator, extractor, or normalizer on every invocation.
Where a step can be deterministic, ship it as code. Scripts are faster, repeatable, and cheap in context because only their result needs to enter the conversation.
Use the model for judgment. Use programs for repeatable mechanics.
A one-line fix that returns as a forty-line diff across three files is not helpful. Unrelated refactors, renames, and cleanup increase review cost and risk.
Tell the skill to touch only what the task requires. Scope discipline is one of the strongest predictors of whether an agent's change is mergeable.
Act 3: Surviving contact with reality
Libraries update. APIs move. Team conventions change. Models interpret instructions differently over time.
A stale skill is worse than a stale comment because the agent may execute it confidently. Treat skills as living operational artifacts with owners, review dates, versioning, and regression scenarios.
A skill you have not rerun in months is a liability you have not measured.
Skills written only from imagination encode the workflow the author hoped for, not the one an agent actually follows.
Run two or three realistic cases. Read the transcripts. Promote repeated helper code into scripts/. Add rebuttals for repeated rationalizations. Document gotchas that catch more than one run. Then rerun.
The skill is debugged from observed behavior, not polished into correctness from the editor.
The three foundations
All nine matter, but three carry the structure:
The rest correct specific failure modes inside a skill that can already be selected, executed, and tested.
Originally published at The Generative Programmer.
