# Skill Schema V2 > Load when creating, auditing, refactoring, or repairing an Agent Skill for reuse, governance, and runtime efficiency. - Skill: `xiaoshiyilangzhao1996-droid/skill-schema-v2-2` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add xiaoshiyilangzhao1996-droid/skill-schema-v2-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/xiaoshiyilangzhao1996-droid/skill-schema-v2-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: xiaoshiyilangzhao1996-droid (https://skillmd.com/u/xiaoshiyilangzhao1996-droid) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xiaoshiyilangzhao1996-droid/skill-schema-v2-2 --- # 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: ```text 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 1. **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. 2. **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/`. 3. **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. 4. **Runtime resources load progressively.** A skill should reveal a compact handle first, then load detailed docs or run scripts only when needed. 5. **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. 6. **No persona hijack unless persona is the product.** Avoid “you are...” identity rewrites, instruction overrides, hidden authority claims, and scope drift. 7. **No hidden local coupling.** Avoid hardcoded credentials, local-only paths, stale install instructions, repo-specific assumptions, or unportable scripts unless clearly marked. 8. **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: ```text 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: ```text 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: ```text 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: ```text Before score: After score: Changed: Remaining risks: Verification evidence: ``` ## Output Format When auditing a skill, respond with: ```text ## Audit: Score: /100 Findings - [FAIL/WARN/PASS] : Required repairs - 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.