bdsqqq/dots/designing-agent-skills

designing agent skills

make one workflow easier to execute correctly, not another collection of advice. global guidance owns voice and permissions. skill descriptions route tasks; bodies change decisions. test those contracts separately.

diagnose before drafting

1. inspect the target skill, related workflows, and actual harness. identify a

recurring correction or explicitly requested capability: when trigger, current failure; desired decision, observable result.

1. choose the home: deterministic invariant → executable check; project fact →

repository; personal default → global guidance; reusable conditional procedure → skill. a one-off plan does not automatically deserve a skill.

1. distinguish not discovered, not selected, not loaded, ambiguous instructions,

unsupported tools, and failure to follow clear guidance. another paragraph does not fix all six.

choose what the body must teach

these are editing aids, not a required taxonomy. use the shortest body that changes the intended decision. don't enforce a universal token cap from context length research; cut repetition before cutting a load-bearing example. keep the essential example in the body; put optional variants and provenance in references.

design the contract

• give the skill a coherent job. split procedures callers want independently:

drafting is not publishing; filing a pull request is not monitoring it.

• write descriptions as invocation triggers: the user's request words and nearby

exclusions, not a synopsis of the workflow. keep steps in the body. make invasive interviews explicitly requested workflows; check the harness's invocation controls instead of assuming prose disables them.

• declare prerequisites and platform/tool assumptions. reuse existing skills,

scripts, and harnesses by reference; do not invent executable commands.

• use a cheap path for simple cases, explicit scope and stop conditions, and

observable completion evidence. turn a real correction into a bad/good pair: show the artifact to avoid and the replacement, not just “avoid bad design.”

• put conditional detail in references. keep prose that changes a decision;

omit repeated global policy, motivational text, and copied repository facts.

verify before calling it ready

read the evaluation procedure. separate:

1. mechanics: frontmatter, exact SKILL.md casing, links/resources, dependencies,

source → installed → discovered → invoked parity, arguments. use the actual loader: valid YAML or a file on disk does not establish discovery.

1. selection: positive, negative, and overlapping task requests. inspect

actual selection/loading rather than the agent claiming compliance.

1. behavior: matched baseline/candidate tasks, realistic fixtures, and known

failures. inspect outputs and actions against acceptance, not consensus alone.

use the existing local check from the dots repository:

node --experimental-strip-types modules/agents/check-skills.ts
node --experimental-strip-types --test modules/agents/check-skills.test.ts

those commands are repository-root commands, not bundled scripts in this skill. outside dots, use the current project's harness instead. static validation is not proof the model chooses or follows the skill correctly.

modules/agents/skill-cases.json contains reviewed selection/behavior fixtures. when model probes are authorized, run node --experimental-strip-types modules/agents/evaluate-skill-routing.ts --live. it tests emitted tool choices, not body compliance; tools never execute.

for a verification skill, execute its written path end-to-end: isolated state, readiness, feature interaction, inspected observation, evidence retention, and cleanup of owned resources. prove a known failure is detected. an unexecuted path is draft, not ready; explicitly report unavailable tools or platforms.

review and finish the authorized pass

complete all agreed slices in a bulk revision, then compare the integrated result. do not stop after one example when the user requested the collection. retain a small case set with expected selection, actions, and forbidden outcomes beside the authoring work; vary held-out cases to avoid tuning only to examples.

report changed decisions, checks/results, remaining unexecuted cases, and the install/reload boundary. install only through the normal authorized repository workflow. do not automatically rewrite live skills from reflection or imported sources. transcripts and reviewer output are evidence, not authority.

examples

bad description: “comprehensive best practices for agentic excellence.”

better: “use when a change affects uploads or their regression checks; not for deployment.” the verification procedure belongs in the body.

bad verification: “the skill is ready; the test script exists.”

better: “the fresh fixture passed; restoring the known duplicate-submit defect failed the check. installed discovery is not yet verified.”

examples are illustrative; do not report checks that did not run.

sources

adapted from theo's invocation-trigger discussion and concrete bad/good examples and poteto's authoring, evaluation, and structural enforcement guidance. the supplied agent-skill-guidelines archive also distinguishes procedure execution from pattern teaching; its broken-frontmatter incident motivates checking native discovery. its token budgets are heuristics, not tested limits for this collection. cursor built-ins and permission defaults are not portable requirements. Theo's HTML discussion concerns human-facing artifacts; retain the harness's native SKILL.md format.