Skill discovery system overview. Keywords: skills, discovery, overview.
This document defines what 鈥渟kills鈥?mean in this template, how skill discovery works across providers, and where the SSOT lives.
In this template, a skill is a routable, reusable guidance bundle:
Skills are designed for progressive disclosure: a skill entrypoint stays lightweight and points to deeper references only when needed.
Rule of thumb:
Each skill has a single SSOT entrypoint under:
/.system/skills/ssot/**/<skill-name>/SKILL.md
Supporting files should live next to the SSOT entrypoint (recommended) under supporting files, examples/, scripts/, and templates/.
Provider-specific entrypoints are generated thin wrappers:
/.codex/skills/<skill-name>/SKILL.md
/.claude/skills/<skill-name>/SKILL.md
Wrappers MUST NOT be hand-edited.
To regenerate wrappers from SSOT:
python scripts/devops/skills/sync_skills.py --regenerate --target repo --publish-set repo_minimal
python scripts/devops/skills/sync_skills.py --regenerate --target integration --publish-set integration_default
To validate in CI / locally:
python scripts/devops/skills/sync_skills.py --check --target repo --publish-set repo_minimal
python scripts/devops/skills/sync_skills.py --check --target integration --publish-set integration_default
Primary mechanism:
description field in each SSOT SKILL.md drives provider-native skill discovery.Optional enhancement:
/.system/skills/config/ (e.g. keyword-based hints), kept minimal to avoid reintroducing a full routing system.repo-routing -> /.system/skills/ssot/repo/repo-routing/SKILL.mdarchitecture-core-mechanisms -> /.system/skills/ssot/repo/architecture-core-mechanisms/repo-architecture-overview/SKILL.mddocumentation-conventions -> /.system/skills/ssot/repo/documentation-conventions/documentation-overview/SKILL.mdscaffolding -> /.system/skills/ssot/repo/scaffolding/new-module/SKILL.mdworkflow-library -> /.system/skills/ssot/repo/workflow-library/workflows-overview/SKILL.mdexecution-plans -> /.system/skills/ssot/repo/execution-plans/execution-plan-authoring/SKILL.mdskill-developer -> /.system/skills/ssot/repo/skill-developer/skill-development-patterns/SKILL.mdbackend-dev-guidelines -> /.system/skills/ssot/backend/backend-dev-guidelines/SKILL.mdfrontend-dev-guidelines -> /.system/skills/ssot/frontend/frontend-dev-guidelines/SKILL.mdroute-tester -> /.system/skills/ssot/repo/route-tester/route-testing-patterns/SKILL.mderror-tracking -> /.system/skills/ssot/repo/error-tracking/error-tracking-patterns/SKILL.md/.system/skills/ssot/<group>/<skill-name>/SKILL.md.name: must match <skill-name> (kebab-case, <= 64 chars)description: single-line, <= 500 chars, include trigger keywordsexamples/).python scripts/devops/skills/sync_skills.py --regenerate --target repo --publish-set repo_minimalpython scripts/devops/skills/sync_skills.py --check --target repo --publish-set repo_minimalpython scripts/devops/skills/sync_skills.py --regenerate --target integration --publish-set integration_defaultpython scripts/devops/skills/sync_skills.py --check --target integration --publish-set integration_default