Scaffold: New Skill Package
This document is the SSOT entrypoint for skill scaffolding.
1. Purpose & Scope
Purpose: Create a new SSOT skill package under /.system/skills/ssot/** and regenerate provider wrappers.
Scope:
- Creates a new skill directory containing
SKILL.md(SSOT entrypoint) - Optionally adds empty supporting directories (supporting files,
examples/, etc.) if the scaffold includes them - Regenerates wrappers under
/.codex/skills/**and/.claude/skills/** - Validates wrapper/SSOT consistency
Out of scope:
- Designing the full skill contents (done iteratively after scaffold)
- Adding new runtime hooks
2. Inputs & Preconditions
Required Inputs
| Parameter | Type | Description |
|---|---|---|
skill_name |
string | Skill name (kebab-case, <= 64 chars) |
description |
string | Single-line discovery description (<= 500 chars; include trigger keywords) |
Optional Inputs
| Parameter | Type | Default | Description |
|---|---|---|---|
group |
string | repo |
Group directory under /.system/skills/ssot/ (not itself a skill) |
scope |
enum | repo |
repo or module scope |
module_id |
string | (none) | Required when scope=module |
skip_regenerate |
boolean | false | Skip provider wrapper regeneration after apply |
Preconditions
- Skill discovery SSOT exists:
/.system/skills/ssot/ - Wrapper generator is available:
scripts/devops/skills/sync_skills.py skill_nameis not already present in SSOT
3. Step-by-Step Flow (AI + Human)
- AI collects required parameters (
skill_name,description) from user - AI runs
--dry-runto preview changes - Human approves the plan
- AI executes the scaffold
- AI records results in workdocs
4. Tools & Scripts
| Tool | Purpose |
|---|---|
scripts/devops/scaffold/new_skill.py |
Orchestrator script |
scripts/devops/skills/sync_skills.py |
Wrapper regeneration + consistency validation |
5. Outputs & Side Effects
Files Created/Modified
/.system/skills/ssot/<group>/<skill-name>/SKILL.md # New SSOT entrypoint
/.codex/skills/<skill-name>/SKILL.md # Generated wrapper (Codex)
/.claude/skills/<skill-name>/SKILL.md # Generated wrapper (Claude)
6. Safety & Rollback
Safety Measures
- Prefer
--dry-runto preview new files/paths - Do not hand-edit generated wrappers (edit SSOT instead)
- Run
sync_skills.py --check --target repo --publish-set repo_minimalafter changes
Rollback Procedure
If scaffold fails or needs reverting:
- Delete the SSOT skill directory:
rm -rf /.system/skills/ssot/<group>/<skill-name>/ - Regenerate wrappers:
python scripts/devops/skills/sync_skills.py --regenerate --target repo --publish-set repo_minimal
7. Related Documents
/.system/skills/ssot/repo/skill-developer/skills-overview/SKILL.md- Skill discovery overview/.system/skills/ssot/repo/skill-developer/agent-skills-integration/SKILL.md- Provider wrapper mapping/.system/skills/ssot/repo/skill-developer/skill-development-patterns/SKILL.md- Skill development patterns/.system/skills/AGENTS.md- Skills system strategy
Source: willyu1007/ai_first_template — distributed by TomeVault.