SkillSpec Docs

This directory contains explanatory project docs. The formal contract remains in ../spec/; the docs here explain purpose, comparisons, launch materials, and design rationale.

The docs are grouped by reader intent. Keep docs/pages/ in place because it is the GitHub Pages source; the other folders are maintained as the human-readable documentation catalog.

Reader Paths

Use these paths when you do not need the whole sequence:

Reader	Start Here	Then Read
Newcomer	Detailed README	Reliability Gap, Why SkillSpec, Prose Skills Vs SkillSpec-Backed Skills, visual explainers
Skill author	Why SkillSpec	Prompt Multiplexer Test Plan, Import To Release, Skill Authoring Lifecycle, Source Map Progressive Reader
CLI tester	Prompt Multiplexer Test Plan	Command Log, Design Documentation QA Process
Maintainer	Design docs	Contract And Trace Methodology, Command Log, spec reference, conformance fixtures
Visual reviewer	Visual explainers	Grammar atlas, Grammar And Conformance

Catalog

Overview

Doc	Purpose
Detailed README	Full user-facing walkthrough.
The Reliability Gap In Agent Skills	Research framing for why prose skills need a checkable reliability layer.
Why SkillSpec	Core motivation and problem statement.
Prose Skills Vs SkillSpec-Backed Skills	Direct comparison between prose-only skills and SkillSpec-backed skills.
Contract And Trace Methodology	Measurement methodology for behavioral contracts, traces, and unproven verdicts.

Community

Doc	Purpose
RFC: SkillSpec v0	Announcement-style RFC for the v0 contract.
Community Outreach	Launch positioning, communities, and outreach steps.
Good First Issues	Starter work for contributors.
Community Post Drafts	Short-form launch and discussion drafts.

Runbooks

Doc	Purpose
Prompt Multiplexer Test Plan	Reference runbook for testing the /skillspec setup multiplexer in Codex and Claude.

Design

• Design docs: maintainer catalog for contract, authoring, runtime, router, and operations design records.
• Core contract docs: grammar, package anatomy, rules, states, imports, and tool boundaries.
• Authoring docs: import, source mapping, workspace authoring, one-shot porting, and shape-specific checklists.
• Runtime docs: sensemaking, execution loops, traces, alignment, capability bootstrap, trampoline, and progressive guidance.
• Router docs: router behavior, guard hooks, duplicate-root selection, execution policy boundaries, and policy profiles.
• Operations docs: command log, QA process, performance, doctor risk, install/release, public reports, crate boundaries, and test matrices.

Visuals And Examples

• Visual explainers: diagram-first workflow explanations for import, runtime, router mode, and durable execution.
• Grammar atlas: visual plates for the grammar, reference graph, semantics, and a worked example.
• Why SkillSpec demo package: runnable side-by-side material that supports Why SkillSpec.

Site Pages

• pages/: GitHub Pages source. Keep this folder shape stable for deployment.

Source Of Truth

When these docs disagree with implementation or reference material, prefer:

1. Rust model, parser, CLI, and tests in ../crates/skillspec-cli/.
2. Schema and reference docs in ../spec/.
3. Conformance fixtures in ../conformance/.
4. Examples in ../examples/.
5. Explanatory docs in this directory.