skillset-codex-development

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/ and skillset.yaml as editable source/state.
• Treat .skillset/, plugins/, .claude/skills, .agents/skills, and .cursor/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 provider config during normal repo work.

Implementation Loop

1. Inspect the closest existing code path before editing. The core modules are packages/core/src/resolver.ts, packages/core/src/render.ts, packages/core/src/build.ts, packages/core/src/config.ts, and packages/core/src/lint.ts; source import remains in apps/skillset/src/import.ts.
2. 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.
3. 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. Run focused tests with bun run test:focused -- <test-files...> so they use the same owned XDG sandbox as aggregate verification.
4. For source-only skill/plugin edits, run bun run skillset:build.
5. Run bun run skillset:check for comprehensive source and workspace diagnostics, and bun run skillset:check:outputs for generated-output freshness when the change touches Skillset source, generated output, or docs/guidance that explain the command boundary.
6. Run bun run check before handoff.
7. Report generated file counts and any skipped checks explicitly.

Repository verification entrypoints create one per-invocation sandbox, preserve HOME, isolate all four XDG roots, and reuse the validated sandbox in nested commands through SKILLSET_TEST_SANDBOX. Set SKILLSET_TEST_SANDBOX_RETAIN=1 only while debugging; the runner prints the retained sandbox and descriptor paths explicitly.

Safety Checks

• Configured generated destination roots must stay inside the repo, outside .skillset/, .skillset/cache/, and .skillset/snapshots/, and unique per active target output. Skillset-owned operational cache paths are reported under .skillset/cache/ but physically resolve to the repo's XDG cache bucket; Git-backed recovery snapshots 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 provider-specific blocks such as claude, codex, or cursor; root defaults.<target> is shorthand, not provider selection.
• Use target-specific model keys such as claude.model, codex.model, cursor.model, or defaults for model choices. Top-level skill model warns in v1.
• compile.unsupportedDestination defaults to error, which gates unsupported/lossy/failed render results before writes. warn, skip, and force soften only lossy or unsupported results while preserving warning diagnostics and lock provenance; failed results still block every policy.
• Use skillset.name for root/plugin explicit identity. skillset.id is unsupported.