modiqo/skillspec

What it solves

SkillSpec addresses the reliability gap in AI agent "skills" (typically defined in SKILL.md files). Because these skills are written as plain text, agents often skip critical safety rules buried in the middle of the document, use undeclared tools, or claim a task is "done" without providing actual proof of completion.

How it works

It converts prose-based skill descriptions into a structured contract using a skill.spec.yml file. This contract explicitly defines routes, forbidden actions, dependencies, and required proof of completion. The system includes a CLI tool called "Doctor" that analyzes existing skills to identify risks—such as high token load or buried obligations—and provides a risk score. Once ported to a contract, the agent's execution can be audited via an alignment summary that records which steps were completed and whether any forbidden actions were taken.

Who it’s for

Developers and operators who build and deploy skills for AI agents (across platforms like Claude Code or Codex) and need a verifiable way to ensure agents follow strict operational constraints.

Highlights

• Risk Assessment: The doctor command scores skills based on agent drift risk and context-position effects.
• Structured Contracts: Moves load‑bearing rules from prose to a YAML specification to prevent agents from skipping instructions.
• Auditability: Generates alignment summaries that provide a durable record of execution rather than just a final answer.
• Router Mode: Helps manage crowded skill libraries by routing requests to the single most relevant skill to improve discovery.
• Harness Integration: Works as a plugin for existing agent harnesses without requiring a new runtime.