| description | Develop and review the local skillset compiler from a Codex-oriented workflow. |
| metadata | {"generated":"skillset@0.1.0","version":"0.1.1"} |
| name | skillset-codex-development |
Skillset Codex Development
Use this skill when working on the local skillset compiler from a Codex-oriented workflow.
Working Context
- Work in
/path/to/skillset.
- Treat
skillset/, skillset.yaml, and skillset/changes/ as editable source/state.
- Treat
.skillset/, plugins-claude/, plugins-codex/, .claude/skills, and .agents/skills as generated or operational output.
- Do not hand-edit generated outputs as source truth.
- Do not publish, globally install, symlink, or mutate user-level Claude/Codex config during normal repo work.
Implementation Loop
- Inspect the closest existing code path before editing. The core modules are
apps/skillset/src/resolver.ts, apps/skillset/src/render.ts, apps/skillset/src/build.ts, apps/skillset/src/config.ts, apps/skillset/src/lint.ts, and apps/skillset/src/import.ts.
- For source contract changes, follow
docs/schema-contracts.md: update packages/schema/src/contracts.ts and packages/schema/src/validate.ts before compiler or Workbench consumers, regenerate artifacts with bun run schema:generate, and verify with bun run schema:check.
- Add or update focused tests or fixtures in the appropriate
apps/skillset/src/__tests__/, packages/schema/src/__tests__/, or packages/workbench/src/__tests__/ file for every behavior change.
- For source-only skill/plugin edits, run
bun run skillset:build.
- Run
bun run skillset:check for current source authoring diagnostics and bun run skillset:verify for generated-output freshness when the change touches Skillset source, generated output, or docs/guidance that explain the command boundary.
- Run
bun run check before handoff.
- Report generated file counts and any skipped checks explicitly.
Safety Checks
- Configured generated destination roots must stay inside the repo, outside
skillset/, skillset/changes/, .skillset/cache/, and .skillset/snapshots/, and unique per active target output. Skillset-owned operational output may live under .skillset/cache/, and recovery backups may live under .skillset/snapshots/.
skillset import should copy into source layout only and refuse to overwrite existing source.
- Use root
compile.targets for provider selection. Do not add bare top-level targets:.
- Keep shared source/config/frontmatter structural validation in
@skillset/schema; do not add a compiler, Workbench, or docs-only field list for the same shape.
- Keep target adapter config and defaults in
claude / codex blocks; root defaults.<target> is shorthand, not provider selection.
- Use target-specific
claude.model, codex.model, or defaults for model choices. Top-level skill model warns in v1.
compile.unsupportedDestination defaults to error, which gates unsupported/lossy/failed render from structured render results before writes; warn, skip, and force are reserved until their non-error semantics are implemented.
- Use
skillset.name for root/plugin explicit identity. skillset.id is unsupported.