SkillVaultskills Browse all 1,000+ skills

AI Engineering · Version 1.1.0 · Reviewed 2026-08-02

AI Skill Authoring Guide

Make AI behavior measurable and safer for skill contract design and skill instruction authoring with evidence, explicit trade-offs, and a verification plan.

4 method steps 5 documented failure modes 5 diagnostic checks 7 quality gates

Designs bounded reusable agent skills with precise triggers, evidence contracts, tool authority, workflow, and evaluation cases. It grounds the decision in the recurring job, target users, examples, failure modes, required tools, authority boundaries, and host constraints and explicitly prevents a role prompt with broad triggers, hidden assumptions, and no observable definition of a correct result.

₹199 one-time

Get this skill archive

Install in your AI coding tool

SkillVault packages this skill in the open Agent Skills format for five leading coding tools.

What this skill helps you do

  • Skill contract design
  • Skill instruction authoring
  • Skill evaluation planning

How AI Skill Authoring Guide works

You provide

The skill files, sibling catalog, host rules, observed failures, and evaluation cases

It inspects

Trigger overlap, authority, context cost, and enforcement paths for skill contract design

It decides

A skill instruction authoring change with regression cases and destination constraints

You verify

The installed portfolio routes a labeled intent corpus correctly and every declared reference resolves

What it checks first

AI Skill Authoring Guide designs bounded reusable agent skills with precise triggers, evidence contracts, tool authority, workflow, and evaluation cases. It grounds the decision in the recurring job, target users, examples, failure modes, required tools, authority boundaries, and host constraints and explicitly prevents a role prompt with broad triggers, hidden assumptions, and no observable definition of a correct result. Use it when the work involves Skill contract design, Skill instruction authoring, Skill evaluation planning.

  1. Trigger precision against neighboring skills, because an excellent method is useless when the wrong requests invoke it.
  2. Whether the skill encodes stable decision knowledge or merely restates a host operation that belongs in a tool or script.
  3. The complete authority chain from instruction to tool call, including confirmation requirements and failure propagation.
  4. Runtime context cost from always-loaded instructions, references, examples, and sibling overlap.
  5. Evaluation coverage for positive, negative, ambiguous, missing-evidence, and conflicting-skill requests.

Failure modes it recognizes

  • Two skills claim the same intent and route nondeterministically depending on superficial wording.
  • A role-style prompt describes expertise but provides no ordered method, refusal boundary, or verifiable deliverable.
  • Detailed references load on every invocation and crowd out the user evidence needed for the actual decision.
  • A skill assumes tools or permissions the host does not provide and converts unavailable execution into confident prose.
  • A narrow failure is patched with another exception until the skill contains contradictory routing and behavior rules.

Answers it will reject

  • Adding every observed failure example to the primary file instead of fixing the shared mechanism or evaluation gap.
  • Combining unrelated jobs into one large skill because they happen to use the same tool.
  • Claiming a skill is portable while hard-coding one host command, repository layout, or authentication model.
  • Judging quality from one successful demonstration without testing sibling routing and negative cases.

Decision rules it applies

  • Split skills when their triggers, evidence, authority, or deliverables differ; share references only when the decision method is genuinely common.
  • Keep routing, safety, and the minimal workflow in the primary file, loading detailed knowledge only when the task requires it.
  • Promote repeated and stable know-how into a skill; leave one-off execution details in a task plan or script.
  • A skill change is incomplete until the original failure becomes a regression case and previously passing cases remain protected.

Evidence it asks for

  • Run a labeled intent corpus through the complete installed skill set and record selected, missed, and competing routes.
  • Measure primary-file and loaded-reference token counts before and after structural changes.
  • Validate every referenced path, declared tool, and output schema from a clean installation.
  • Execute positive, negative, ambiguous, and tool-failure evaluation cases against the final packaged revision.

The method inside

  1. Turn skill contract design into explicit functional requirements and quality-attribute constraints.
  2. Model the critical path, state, trust, and failure boundaries that govern skill instruction authoring.
  3. Compare viable designs for skill evaluation planning against weighted constraints and operational ownership.
  4. Select a design with consequences, rollout stages, observability, and a reversible adoption path.

Deliverables

  • Skill contract design assessment
  • Skill instruction authoring decision and action plan
  • Skill evaluation planning verification checklist

Evidence requirements

  • Prompts, model/version, tools, retrieval path, and examples
  • Evaluation dataset and failure cases
  • Latency, cost, privacy, and policy constraints

Quality gates

  • Every material claim traces to supplied evidence or is labeled as a hypothesis.
  • The response follows the declared deliverable contract.
  • No execution, access, measurement, or verification is invented.
  • Secrets and personal data are redacted rather than repeated.
  • The user receives a concrete independent verification step.
  • The relevant failure modes in this domain were considered rather than only the reported symptom.
  • No listed anti-pattern was recommended as a solution.

Example task

Input

Apply the ai skill authoring guide to our current skill contract design work. We need a concrete decision, bounded changes, and evidence that the result is correct.

Expected output

Start with the recurring job, target users, examples, failure modes, required tools, authority boundaries, and host constraints. The highest-risk failure is a role prompt with broad triggers, hidden assumptions, and no observable definition of a correct result. Encode a repeatable decision method, explicit exclusions, and independent verification rather than a persona. Verify the result by running positive, negative, boundary, missing-evidence, and prompt-injection evaluation cases.

Boundaries and compatibility

Ideal for

  • Skill contract design: produce a decision or artifact grounded in supplied evidence.
  • Skill instruction authoring: produce a decision or artifact grounded in supplied evidence.
  • Skill evaluation planning: produce a decision or artifact grounded in supplied evidence.

Out of scope

  • Treating prompt text as a security boundary
  • Claiming model quality from a handful of demos

Agent compatibility

  • GitHub Copilot Agent Skills
  • Cursor Agent Skills
  • Claude Code Skills
  • OpenAI Codex Skills
  • JetBrains Junie Skills

Tool policy: Advisory by default. No tools are assumed. If the host provides tools, use read-only evidence gathering unless the user explicitly approves a scoped write or execution action.