AI Tools and Skills Governance

Canonical reference for the AI capability system. Covers the current operational layout under ai-tools/, target architecture, skill classification taxonomy, and migration rules across Claude, Codex, Cursor, and Windsurf.

AI Tools and Skills Governance

Source of truth for the AI capability system in this repo. Covers the current operational layout, target architecture, skill classification, and migration rules that keep agent entrypoints working while logic is consolidated.

---

Current Active Root

ai-tools/ is the governed root for AI skills, rules, registry artefacts, and generated agent packs.

Surface	Current path	Role
Canonical templates	ai-tools/ai-skills/templates/	Source-of-truth for portable skill definitions
Local skill roots	ai-tools/ai-skills/*/SKILL.md	Repo-consumed skill artefacts and local companion references
Generated exports	ai-tools/agent-packs/**	Generated packs, manifests, and portable skill exports
Registry	ai-tools/registry/**	Canonical inventory, schema, and coverage metadata
Governance docs	ai-tools/ai-skills/skill-spec-contract.md	Human-readable contract and governance guidance
Runtime adapters	AGENTS.md, .claude/CLAUDE.md, .github/AGENTS.md, .cursor/rules/**, .windsurf/rules/**, .augment/rules/**	Agent-facing entrypoints that must remain thin

Transition rule: Current files are operational surfaces that must keep working during migration. Do not treat directory names as the final architecture.

---

Target Architecture

ai-tools/
  canonical/
    skills/
    references/
    dispatchers/
    governance/
    packaging/
  adapters/
    claude/
    codex/
    cursor/
    windsurf/
  generated/
    packs/
    manifests/
    indexes/
  registry/

Target layer	What belongs there
canonical/skills	Atomic, reusable repo-governed skill logic
canonical/references	Shared references, companion documents, and reusable assets
canonical/dispatchers	Top-level workflow orchestrators that route atomic skills
canonical/governance	Contract docs, taxonomy docs, lifecycle rules, and policy documents
canonical/packaging	Packaging metadata that drives sync/export flows
adapters/	Thin agent-specific wrappers, registrations, prompts, or runtime glue
generated/	Generated packs, manifests, and indexes; never hand-edited
registry/	Canonical machine-readable inventory and governance coverage metadata

---

Classification Model

Type

Value	Meaning
atomic	One bounded capability; reusable building block
dispatcher	Routes or orchestrates a multi-step workflow using atomic skills
adapter	Agent-specific wrapper, registration, or runtime-facing shim
governance	Contract, packaging, inventory, validation, or policy surface
reference	Companion material consumed by skills or adapters but not executable logic

Concern

Value	Meaning
review	Review packets, change review, contradiction checks, remediation guidance
research	Fact-finding, source verification, evidence gathering, claim mapping
authoring	Page writing, copy, structure, IA, and editing guidance
repo-ops	Repo cleanup, handover readiness, governance operations, inventories
validation	Gate checks, staged verification, browser/link/testing workflows
migration	Path moves, structural transitions, compatibility sweeps
release	Shipping, publish readiness, release validation, rollout support
agent-runtime	Agent-specific runtime, setup, sync, packager, adapter behaviour

Scope

Value	Meaning
repo	Repo-governed artefact or workflow
agent	Agent-specific surface consumed in a repo context
platform	External tool, plugin, or platform-owned capability
generated	Generated output only
personal-global	User-local or machine-local surface outside repo governance

Status

Value	Meaning
active	Current governed surface
experimental	Active but not yet locked
generated	Derived output; not hand-authored
deprecated	Still present for compatibility, slated for retirement
retired	Historical reference only

---

Artefact Rules by Layer

Canonical: Logic must exist exactly once. Templates and local repo skill bodies must not diverge semantically. Dispatcher definitions belong here, not in agent adapters.

Adapter: May exist many times. Must not own unique workflow logic or policy. May add discovery wording, invocation syntax, or runtime-specific guidance only.

Generated: Never edited by hand. Must derive from canonical data. Drift between canonical and generated surfaces is a blocking quality issue.

Global/Platform: May be documented but are not part of repo-governed canonical logic unless explicitly imported and governed.

---

Dispatcher Model

Dispatchers orchestrate; they do not own unique atomic logic. A dispatcher must declare ordered child capabilities, required inputs, validation gates, and output artefacts. Agent-specific execution differences belong in adapters, not in the canonical dispatcher.

Phase 1 dispatcher family

Dispatcher	Purpose
research-review-packet	Gather evidence, contradictions, claim maps, and review packet outputs
review-fix	Turn review findings into scoped fixes with validation
handover-readiness	Produce confidence signals for repo handoff
page-ship	Take a docs page from verified draft to shippable state
repo-cleanup-handover	Consolidate repo cleanup and handover outputs

---

Migration Rules

Keep in place now: ai-tools/ai-skills/templates/**, ai-tools/ai-skills/*/SKILL.md, ai-tools/agent-packs/**, existing agent-native adapter files.

Introduce as architecture, not physical churn: canonical/adapters/generated/registry separation, dispatcher families, script-like classification fields, compatibility mapping from legacy category values.

Do not do in this phase: move ai-tools/ into operations/, break .claude/skills discovery or other agent-native entrypoints, hand-edit generated pack files as if they are canonical.

Alias policy: Old entrypoints stay operational until their replacements are live and documented. Compatibility wrappers are acceptable during migration. Silent divergence is not acceptable.