Name: skill-schema-v2
Author: xiaoshiyilangzhao1996-droid

Imported from xiaoshiyilangzhao1996-droid/Skill-Schema-V2 (SKILL.md). Install upstream with npx skills add xiaoshiyilangzhao1996-droid/Skill-Schema-V2. Copyright stays with the author.

Skill Schema V2

This is the compatibility entrypoint for the v2 skill schema. The installable v2 package is in skill-schema-v2.skill/.

Use it when a user is designing, auditing, refactoring, or repairing an Agent Skill.

Core Rule

A skill has three surfaces:

Routing Surface: name + description + frontmatter
Contract Surface: goal + inputs + permissions + evidence + output + verification + handoff
Runtime Boundary Surface: docs + examples + scripts + operators + fallback paths

The three surfaces must be aligned. If the description routes one task, the contract must govern that task, and runtime resources must support that task without forcing irrelevant context into the model.

What Changed in v2

v2 adds three 2026 findings:

Contractual Skills: skills should be readable task contracts with explicit boundaries and acceptance criteria.
138K SKILL.md reusability study: routing defects, body bloat, poor resources, safety issues, portability gaps, and persona/scope conflicts are measurable defects.
SkillSmith: raw skill injection wastes context; skills should expose minimal runtime boundaries and load detail progressively.

Audit Output

When auditing, score out of 100:

Area	Points
Routing	15
Contract	20
Runtime Boundary	15
Reusability	15
Safety	15
Signal Density	10
Versioning	5
Self-Consistency	5

Runtime Resources

Load only as needed:

skill-schema-v2.skill/SKILL.md for the complete v2 contract.
skill-schema-v2.skill/docs/v2-design-spec.md for design rationale.
skill-schema-v2.skill/docs/audit-rubric.md for scoring details.
skill-schema-v2.skill/docs/repair-playbook.md for repair patterns.
docs/paper-digests.md for paper evidence.

Install skill-schema-v2 and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

{ "ocm": "1", "id": "xiaoshiyilangzhao1996-droid-skill-schema-v2-skill-schema-v2", "kind": "skill", "name": "skill-schema-v2", "description": "Load when creating, auditing, refactoring, or repairing an Agent Skill for reuse, governance, and runtime efficiency.", "publisher": "xiaoshiyilangzhao1996-droid", "version": "1.0.0", "capabilities": { "domains": [ "general" ], "tags": [ "skill-md", "github" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "Load when creating, auditing, refactoring, or repairing an Agent Skill for reuse, governance, and runtime efficiency." ], "primary": false, "metadata": { "source": { "provider": "github", "repository": "https://github.com/xiaoshiyilangzhao1996-droid/Skill-Schema-V2", "path": "SKILL.md", "ref": "8feafdb7ed1ab719e17212e2d5b46a675bfd38dd", "url": "https://github.com/xiaoshiyilangzhao1996-droid/Skill-Schema-V2/blob/8feafdb7ed1ab719e17212e2d5b46a675bfd38dd/SKILL.md", "key": "xiaoshiyilangzhao1996-droid/Skill-Schema-V2/SKILL.md" } }, "instructions": "# Skill Schema V2\n\nThis is the compatibility entrypoint for the v2 skill schema. The installable v2 package is in `skill-schema-v2.skill/`.\n\nUse it when a user is designing, auditing, refactoring, or repairing an Agent Skill.\n\n## Core Rule\n\nA skill has three surfaces:\n\n```text\nRouting Surface: name + description + frontmatter\nContract Surface: goal + inputs + permissions + evidence + output + verification + handoff\nRuntime Boundary Surface: docs + examples + scripts + operators + fallback paths\n```\n\nThe three surfaces must be aligned. If the description routes one task, the contract must gover", "cost": { "context_tokens": 448 } }

skill-schema-v2

About

Skill Schema V2

Core Rule

What Changed in v2

Audit Output

Runtime Resources

Install skill-schema-v2 and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews