# Skill Engineering > Author and maintain Agent Skills: routing metadata, body content, bundled references and scripts, evaluation, and distribution. - Skill: `xobotyi/skill-engineering` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add xobotyi/skill-engineering` - Raw SKILL.md: https://api.skillmd.com/api/skills/xobotyi/skill-engineering/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: xobotyi (https://skillmd.com/u/xobotyi) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xobotyi/skill-engineering --- A skill is instruction text. Invoke `prompt-engineering` for the wording, instruction budget, and timelessness rules that govern every line written here. This skill covers only what is specific to the skill artifact — routing metadata, packaging, progressive disclosure, and evaluation. **A skill stabilizes a procedure the agent performs unreliably.** It is not a place for knowledge the model already has, and it is not documentation. Value concentrates in procedural anchoring — setup order, tool sequence, the check that catches a specific failure — not in explanation. ## Decide whether the behavior belongs in a skill - **Write a skill only where the model fails the procedure without it.** Skills pay off where the model is weak and cost where it is already competent: a skill on a task the model already handles adds tokens, adds an applicability judgment it can get wrong, and narrows the recovery path it would otherwise have found. - **One skill per procedure a user would name in a single request.** If one request needs two of these skills, they are one skill; if one skill answers two unrelated requests, it is two. - **Put a prohibition that must hold every time in a hook.** Prose steers; the host's lifecycle mechanism enforces. - **Put work that needs a clean context and returns a summary in a subagent**, and connection to an external system in a tool or server. Skills carry procedure; tools carry capability. Archetype and scoping — the workflow, knowledge, and coding-discipline shapes with their structural templates, the scope-sizing tests, negative triggers, and skill composition: [`${CLAUDE_SKILL_DIR}/references/archetypes.md`]. Read it before writing the body, because the archetype decides the structure. ## Write the description as routing code The description is the only part of a skill that is always in context, and it is where most skills fail: over half of public skills carry routing metadata that cannot route. - **Use the form `[Verb] [what]. Use when [trigger].`** A description that says only what the skill does gives the model nothing to fire on. - **Discriminate against the neighbors.** Name the boundary that separates this skill from the sibling that matches the same words. Selection precision collapses as the candidate pool grows — from roughly 30% at five candidates to a few percent at a hundred — so a description competes, it does not merely describe. - **Front-load the use case and keep it under 250 characters.** Listings are budgeted and truncate. - **Write the triggers in the words a user would type**, including the case where the user never names the domain. - **Keep routing information out of the body and write it in third person.** The body is read after the routing decision is made, and a mixed point of view degrades discovery. ## Prefer proscriptive content Slice ablation on skills measured to help: anti-pattern rules are the only content type with a directionally reliable effect. Positive rules are neutral. Worked examples are the most expensive slice by token count. - **Write the gotcha, not the tutorial.** An environment-specific fact that defies a reasonable assumption is the highest-value line in a skill — the field named one thing in one service and another in the next, the endpoint that returns success while the work silently failed, the table that is append-only. - **Build the gotchas from observed failures.** Every correction made while the skill runs is a candidate line. This is the most direct way to improve a skill. - **Encode knowledge local to a repository, framework, or service.** Content the model could generate on demand earns nothing; the trait that separates high-quality public skills is knowledge it could not. - **Delete anything the model already does.** A rule that changes nothing costs the same as one that changes everything. - **Give one default with an escape hatch, never a menu**, and do not repeat the skill name as a heading. ## Calibrate prescriptiveness against fragility Prescription buys consistency and pays in recoverability. After a first-attempt mistake, prescriptive content restricts the recovery path the model would otherwise have taken — which is why degradation concentrates on tasks the model was already going to pass. - **Prescribe where a wrong order or a wrong flag causes damage that is not automatically recoverable** — a migration sequence, a destructive operation, a released artifact. State that the sequence is exact. - **Give constraints instead of steps everywhere else**, and let the model pick the path. - **Omit worked examples when the target is a frontier model.** In one ablation the same example slice moved mid-tier models several points up and the strongest model fifteen points down, by suppressing its own better priors. An output template is safe — it pins a shape without demonstrating an approach. ## Split by load condition, not by topic The body loads on every activation and stays in context; bundled files cost nothing until read. Mandatory body text is where context cost concentrates — in one failure analysis, body bloat accounted for 43 of 46 context-overhead regressions while supplementary material accounted for 3. - **Keep in the body only what applies on every run.** Everything conditional belongs in a bundled file. - **State the condition that loads each file** at the point the condition arises. "Read the API-errors reference when the API returns a non-200 status" works; "see `references/` for details" does not. Whether a reference is ever read is unmeasured, so an unconditioned pointer is a guess. - **Keep references one level deep and name each file for its content.** Put templates and static resources in `assets/`. - **Bundle a script for a deterministic operation, or for work that transcripts show being reinvented.** Script code never enters context; only its output does. - **Make execution intent unmistakable.** "Run `scripts/x.py`" and "see `scripts/x.py` for the algorithm" must not be confusable, because some hosts read a bundled script where others execute it. Packaging and cross-host limits — the six-field portable contract, the plugin package format, where extra frontmatter causes a hard error, distribution scopes: [`${CLAUDE_SKILL_DIR}/references/portability.md`]. Read it before shipping a skill to a host other than the one it was written on. Host behavior — the full frontmatter field set, the listing budget and its truncation order, content lifecycle and compaction limits, invocation control, per-turn permissions, substitutions, dynamic context injection, forked execution, precedence, version gates: [`${CLAUDE_SKILL_DIR}/references/claude-code.md`]. Read it when authoring for Claude Code or debugging why a skill does not activate. ## Verify against a baseline - **Run the host's structural validator on every change.** It is cheap and catches the defects that stop a skill loading at all. It does not predict whether the skill helps: measured against live effect, structural and judge scores both correlate at approximately zero. - **Measure activation and behavior separately before other people depend on the skill**, each against a no-skill baseline in a fresh session. Use the host's own eval tooling; where none is available, say the skill is unmeasured rather than building a harness. - **Check the new rules against the rules already loaded.** The executing model resolves contradictions with judgment, which is what stops it from reporting them — so its silence is not evidence of consistency. Test in a fresh context, or with a different model than the one that will execute. - **Condition the verification a skill prescribes on task uncertainty, change size, and risk.** Mandatory verification is the largest measured source of cost regression — skills turn optional checks into work performed every time. Where correctness is machine-checkable, prescribe a validation loop whose errors name the offending value and the accepted set. Trigger sets, near-miss negatives, assertion design, grading, the iteration loop, and the available tooling: [`${CLAUDE_SKILL_DIR}/references/evaluation.md`]. Read it when measuring or tuning a skill. ## Maintain against the substrate - **Re-measure on a model or host upgrade.** A skill decays without being edited: as the baseline model improves, its marginal value shrinks while absolute performance stays high. A skill can be well written and not worth loading. - **Treat utility as specific to one model.** Per-pair utility is near-uncorrelated across model backends, and most skill-task pairs help on one model and hurt on another. A single ranking does not transfer. - **Delete a skill that stops earning its slot.** Every installed skill costs listing budget and competes for selection against its neighbors. What not to ship, how to review a third-party skill, scanner blind spots, and the permission hazards a checked-in skill carries: [`${CLAUDE_SKILL_DIR}/references/security.md`]. Read it before publishing a skill or installing one.