SkillSpec tackles the unreliability of AI agents executing natural language instructions (SKILL.md) by transforming them into structured, testable contracts. It targets developers building or relying on agent skills, offering enhanced reliability, testability, and provability through risk assessment and auditable execution records, without requiring new agent runtimes.

How It Works

SkillSpec operates via a CLI tool that analyzes existing prose-based SKILL.md files. It assesses skills for risks like context-position effects, buried obligations, and undeclared dependencies using the "Doctor" report. The core functionality involves "porting" these prose skills into a structured skill.spec.yml contract, defining routes, rules, forbidden actions, and proof expectations. This contract, alongside a compiled loader, allows agents to execute skills more reliably, generating an auditable "alignment summary" post-execution detailing the actual steps taken against the contract.

Quick Start & Requirements

Install the CLI via curl -fsSL https://skillspec.sh/install.sh | sh. Alternatives include cargo install skillspec or using prebuilt binaries from the releases page. Requires integration with agent harnesses like Codex, Claude, or Agents. A Justfile is provided for local development, offering commands for building, testing, and installing the skill into various harnesses.

Highlighted Details

• Doctor Risk Report: Assesses skills for discovery risk, context load, obligation placement, dependency declaration, and proof requirements, providing a quantifiable risk score.
• Structured Contracts: Converts informal SKILL.md into formal skill.spec.yml defining skill behavior, rules, and dependencies.
• Auditable Execution Records: Generates alignment summaries post-run, detailing route selection, step completion, and adherence to contract rules.
• Router Mode: Facilitates routing to specific skills when harness listing budgets limit discovery.

Maintenance & Community

The repository is actively maintained, with installation scripts and a Justfile suggesting a structured development process. Specific community links (Discord/Slack) or notable contributors are not detailed in the provided text.

Licensing & Compatibility

SkillSpec is dual-licensed under MIT and Apache License 2.0, permitting commercial use and integration into closed-source projects. Contributions are accepted under the same terms.

Limitations & Caveats

SkillSpec is not a replacement for agent runtimes or orchestration platforms; it enhances existing ones. Enforcement of tool boundaries remains the responsibility of the agent harness. The "Doctor" report highlights potential risks, but SkillSpec itself does not guarantee perfect agent adherence, only provides mechanisms for assessment and auditing.