| name | skill-schema-v2 |
| description | Load when creating, auditing, refactoring, or repairing an Agent Skill for reuse, governance, and runtime efficiency. |
| version | 2.0.0 |
| last_updated | 2026-06-02 |
| depends | [] |
| metadata | {"author":"yinyo","category":"skill-engineering","sources":["Contractual Skills, arXiv:2605.22634","What Keeps Agent Skills from Being Reusable?, Agent Skills 2026","SkillSmith, arXiv:2605.15215"]} |
Skill Schema v2
Use this skill to design, audit, or repair Agent Skills as reusable capability packages. v2 is based on three current findings:
- A skill is a readable task contract, not a prompt fragment.
- A skill must be routable and reusable, not just useful in its original chat or repo.
- A skill should expose a minimal runtime boundary, not inject every reference into context.
Core Model
Every serious skill has three surfaces:
Routing Surface
name + description + frontmatter
Decides whether the skill is loaded.
Contract Surface
goal + inputs + permissions + evidence + output + verification + handoff
Decides what correct behavior means.
Runtime Boundary Surface
docs + examples + scripts + operators + fallback paths
Decides what gets loaded or executed after selection.
These surfaces must not contradict each other. If the description routes one task, the contract must govern that task, and runtime resources must support that task.
Hard Rules
- Description is routing metadata. It must start with
Load when... or an equivalent trigger phrase, describe when to load the skill, and stay short enough for startup routing.
- SKILL.md is not a knowledge warehouse. Keep it as the routing and contract surface. Put detailed references, examples, templates, long rules, and papers in
docs/, examples/, templates/, or scripts/.
- Use contract fields only when they reduce ambiguity. Do not add enterprise fields as ceremony. Add goal, inputs, permissions, evidence, output, verification, or handoff only when they affect behavior.
- Runtime resources load progressively. A skill should reveal a compact handle first, then load detailed docs or run scripts only when needed.
- Safety belongs in both language and enforcement. The skill can state permissions, human gates, and evidence policy; tools, adapters, guardrails, tests, or humans must still enforce high-risk actions.
- No persona hijack unless persona is the product. Avoid “you are...” identity rewrites, instruction overrides, hidden authority claims, and scope drift.
- No hidden local coupling. Avoid hardcoded credentials, local-only paths, stale install instructions, repo-specific assumptions, or unportable scripts unless clearly marked.
- Every repair needs verification. A repaired skill must be re-audited against routing, contract, runtime boundary, safety, portability, and self-consistency.
Minimal Contract
For low-risk skills, use the compact contract:
Goal: what the skill helps finish.
Load when: exact trigger conditions.
Inputs: required and optional user/context inputs.
Workflow: only the steps that change behavior.
Output: expected final artifact or response.
Verification: how to know the skill worked.
Boundaries: what the skill must not do.
Runtime resources: which docs/examples/scripts to load only when needed.
Full Contract
Use the full contract for enterprise, tool-calling, high-risk, multi-agent, publication, finance, legal, privacy, deployment, or external-send skills:
Goal
Audience
Inputs
Context sources
Workflow
Permissions
Human gates
Constraints
Evidence policy
Output contract
Quality bar
Verification
Handoff / pause rules
Runtime boundary
Fallback path
Do not use the full template for one-off, low-risk, no-tool skills. That creates body bloat.
Audit Rubric
Score out of 100:
| Area | Points | Checks |
|---|
| Routing | 15 | name, description, trigger clarity, no body-only routing |
| Contract | 20 | goal, inputs, output, verification, boundaries |
| Runtime Boundary | 15 | progressive docs/examples/scripts, minimal context, fallback |
| Reusability | 15 | portable paths, organized resources, no stale boilerplate |
| Safety | 15 | permissions, human gates, prohibited content, persona/scope |
| Signal Density | 10 | no model-known filler, no process theater |
| Versioning | 5 | SemVer, last_updated, changelog or release note |
| Self-Consistency | 5 | no conflicts across description/body/docs/scripts |
Critical failures cap the score at 60:
- missing or non-functional description
- hardcoded secrets
- destructive actions without approval boundary
- persona override unrelated to task
- SKILL.md so large that routing/contract content is buried
- output contract contradicts workflow or runtime resources
Repair Protocol
Use risk-based repair:
Low risk: frontmatter normalization, file moves, version sync, broken links
-> repair directly, then report.
Medium risk: description rewrite, contract-field rewrite, runtime boundary rewrite
-> show before/after and rationale.
High risk: deleting content, changing safety gates, changing permissions, changing external-send behavior
-> list exact changes and require confirmation.
After repair, run a second audit and report:
Before score:
After score:
Changed:
Remaining risks:
Verification evidence:
Output Format
When auditing a skill, respond with:
## Audit: <skill-name>
Score: <n>/100
Findings
- [FAIL/WARN/PASS] <area>: <concrete issue>
Required repairs
- <highest impact first>
Self-consistency check
- Routing vs contract:
- Contract vs runtime resources:
- Safety language vs enforcement:
Suggested next version
- version:
- changed files:
- verification:
Runtime Docs
Load only what is needed:
docs/v2-design-spec.md for full design rationale and paper synthesis.docs/audit-rubric.md for detailed scoring checks.docs/repair-playbook.md for repair patterns.examples/v2-audit-report.md for report shape.
