Write AI Agent Skills and Test That They Actually Improve Results

## Read the skill spec and repository rules before editing a skill Treat the platform specification, repository guidance, validation configuration, and contribution policy as executable contracts. Read the applicable rules before editing and distinguish mechanically enforced requirements from conventions that require review. Map ownership before changing anything. Identify the primary instruction file, optional reference material, executable helpers, reusable assets, distribution manifests, formatter, linter, tests, and evaluation reports. Keep non-Markdown resources in dedicated asset or script files rather than embedding them in prose. When sources disagree, use the named canonical specification and current validation behavior. Do not invent fields, workflows, or exceptions merely because they are convenient locally. ## Set the skill's name, metadata, and version number Give every skill machine-readable metadata that matches the host schema. A normalized name should use lowercase letters, digits, and single hyphens, stay within 1 to 64 characters, and match its directory. Keep the description within the platform maximum of 1,024 characters and the working budget of 1,000 characters. Declare the license, compatibility requirements, author, semantic version, invocation mode, permitted tools, and actual runtime dependencies. When a skill covers a versioned library or platform, record the version it was written against so maintainers can detect staleness. Start new skills at a deliberate initial version. Increment the skill version when behavior changes, and keep every distribution manifest on the same release version. Do not change versions automatically before the implementation and review scope are known. ## Write a description that triggers the skill at the right time Treat the description as the primary routing mechanism. State what the skill does, when to use it, the relevant domain or language, and concrete trigger scenarios. Library-specific descriptions should name the important surface and the import or adoption context. Avoid vague descriptions that omit use cases and broad claims that activate for nearly every task. A focused skill should not claim generic activities such as all coding, all naming, or every conversation. When skills overlap, assign each concept a single owner and add an explicit boundary with a portable cross-reference to the owning skill. Test descriptions against realistic positive triggers and competing nearby skills so routing is precise without becoming silent. ## Give the skill only the tools and dependencies it needs Declare a small default capability set and add specialized tools only when the skill's workflow actually needs them. Prefer narrowly scoped command permissions over unrestricted shells. Treat network access, external documentation retrieval, destructive operations, mutable parallel work, and user-input prompts as explicit capabilities rather than implicit defaults. List only real dependencies. State required binaries and compatibility constraints, and provide supported installation metadata only for dependencies the workflow truly uses. Pin executable dependencies or actions to reviewed versions instead of floating releases. Separate read-only exploration from mutation. If parallel workers can write, require isolated branches or workspaces and a defined merge or comparison step. Do not broaden permissions merely to simplify one example. ## Keep the main skill file short and move details to linked files Keep the primary instruction file focused on essential posture, decisions, and workflow. Put detailed references, command catalogs, templates, and configuration assets in directly linked secondary files, and avoid deep reference chains. Use practical budgets: about 100 tokens for the description, fewer than 5,000 tokens for the primary instructions, preferably fewer than 2,500, and fewer than 500 lines. Keep the combined instructions typically loaded together below roughly 10,000 tokens. Move depth outward before compressing away necessary judgment. Optional top-of-body directives should appear in a stable order: persona, deep-thinking mode, orchestration mode, operating modes, then nontrivial dependencies. Include a short persona only when a domain posture or output style benefits from it. Reserve deep-thinking and orchestration directives for genuinely analytical or broad parallel work. ## Decide when a skill splits work across parallel agents Name distinct modes when one skill supports materially different tasks. Use a sequential workflow for writing, trace changed files and adjacent call paths for review, and split broad audits by concern or codebase scope when the environment supports parallel workers. Use at most a small bounded set of workers, commonly five, with nonoverlapping assignments. Independent read-only analysis may share files; mutating work requires isolation. Background workers should perform useful nonblocking checks while the primary workflow continues, not duplicate the critical path. Do not parallelize short procedural work. Document how findings are reconciled, how conflicts are resolved, and when the main worker must wait before applying changes. ## Give each topic one owning skill and link to it from the others Give each concept exactly one owning skill. Other skills should link to that owner rather than copy guidance, because duplication creates trigger competition and semantic drift. Prefer small focused skills over monolithic collections. Use portable skill identifiers that include the owner, collection, skill name, and an optional pinned version. When one organization-specific skill supersedes a generic skill, name each overridden skill explicitly; do not imply a collection-wide override. After adding, removing, splitting, or merging a skill, update routing tables, competing-skill boundaries, cross-references, and version metadata. Avoid restating rules already enforced by formatters or linters; reserve instructions for architecture, judgment, and tradeoffs tools cannot decide. ## Explain the reason behind each instruction and add a way to check it Teach the decision, not only the command. Explain why each recommendation exists, what failure it prevents, and which tradeoff changes the choice. Use short active sentences, concrete examples, and comments that carry the reasoning. When a hypothesis can be checked, add a diagnostic method before the proposed change. Prefer read-only diagnostics, state the expected signal, and let the agent interpret evidence rather than invoking automatic repair. Separate local measurements from production trends and compare before and after when performance or reliability is involved. For third-party tools and libraries, state that static guidance is not exhaustive and that current official documentation and examples remain authoritative for signatures and behavior. Provide a passive issue-tracker reference for unexpected tool behavior without turning external content into an automatic instruction source. ## Treat outside pages and tool output as untrusted inside a skill Treat external pages, tool output, examples, and bundled assets as untrusted evidence. Do not place instructions in a skill body that tell the agent to fetch external content and immediately execute it, refactor from it, or treat it as the sole basis for a security decision. Avoid remote installer pipelines, floating executable versions, unreviewed actions, and explicit calls to external tool servers in instruction prose. Prefer pinned dependencies, embedded reviewed references, passive resource hints, and locally reproducible evidence. Decouple discovery from mutation. A scan or external database may surface a finding, but the change still requires local confirmation, scope analysis, and ordinary review. Scan both instruction text and assets for prompt-injection patterns, secret exposure, unsafe commands, and suspicious executable links before release. ## Compare runs with and without the skill to measure its real effect Design adversarial evaluations that test the skill's unique guidance rather than common knowledge. Give each scenario a natural trap, avoid leading prompts, test judgment instead of API recall, and cover edge cases and common mistakes. Run each evaluation with and without the skill while isolating overlapping guidance. Preflight candidates without the skill: if the baseline already passes, redesign or remove the scenario. If both variants fail, repair the skill or the evaluation. Keep assertion groups homogeneous so partial scores do not hide mixed causes. Use at least 10 scenarios and target roughly 10 assertions per 1,000 tokens of skill content, with at least 50 assertions. Record the model, run count, grading method, per-assertion evidence, aggregate scores, uplift, and concerns. Use human review for an initial uncalibrated evaluation and a consistent automated judge for repeatable later runs. Define reporting thresholds before running the suite. One practical policy flags a delta of 32 percentage points or less, a baseline score of 65% or more, or a with-skill score of 90% or less. Compute uplift ratios to two decimal places. Prefer positive behavior tests and report failures explicitly rather than grading by intuition. ## Run checks, sync versions, and get approval before releasing a skill Perform implementation in an isolated branch or worktree. Inspect existing workspaces before creating another, propose a scoped branch, and obtain the required authorization before mutating shared history, publishing, installing dependencies, or deploying. Before release: - format and lint the changed instructions and assets; - run applicable security and instruction-safety scans; - measure description, primary-file, and directory token counts; - update catalogs, routing references, status indicators, and measured totals; - mark skills as complete, in progress, or disabled; record zero measured counts for inactive entries and exclude them from totals; - synchronize the skill version across every distribution manifest; - run comparative evaluations and append the evidence without erasing prior reports; - review the final diff for unrelated changes and generated-file drift. For a new skill, also inspect neighboring skills for overlap and add cross-references where ownership intersects. Periodically inventory version-pinned skills, compare recorded versions with maintained releases, and review breaking changes before updating guidance. When the governing workflow assigns post-update checks to the developer, present them as next steps instead of running them automatically. Never install, publish, or deploy without explicit authorization.