Project Local Skill Generator

Purpose

Create short repo-specific .codex/skills that teach Codex how to operate in this project day to day, while keeping reusable harness authoring skills in the plugin.

Inspect First

• existing .codex/skills
• AGENTS.md, nested AGENTS.md, docs, scripts, feature state, progress, decisions, runtime docs, UI docs, review docs, and validation commands
• whether each proposed local skill has real repo artifacts to link to

Procedure

1. Suggest local skills from evidence.

   • Use scripts/suggest_project_local_skills.py from this plugin.
   • Recommend only skills backed by existing repo files.
   • Classify suggestions as daily, on_demand, or library so high-frequency workflows stay easy to find without bloating root instructions.
   • Skip skills whose artifacts are missing instead of inventing local policy.

2. Generate thin local wrappers.

   • Use scripts/generate_project_local_skills.py.
   • Write to .codex/skills/<local-skill-name>/SKILL.md.
   • Default local skills are project-feature-workflow, project-session-handoff, project-definition-of-done, project-runtime-debugging, project-ui-workflow, and project-review-protocol.
   • Stack-specific local skills may include project-bun-workflow, project-frontend-workflow, project-browser-qa, project-api-workflow, project-data-workflow, project-docker-runtime, and project-decision-log when matching artifacts exist.
   • Trajectory local skills may include project-trajectory-supervisor when task traces, trajectory policy, or scripts/check-trajectory-risk exists.

3. Preserve local edits.

   • Inspect existing local skill files before generation.
   • Do not overwrite existing local skills unless the task explicitly requests refresh or overwrite behavior.
   • Prefer adding missing skills over regenerating edited ones.

4. Keep plugin and project roles separate.

   • Local skills name exact repo files and commands.
   • Local skills route heavy harness authoring back to plugin skills.
   • Do not copy full plugin skills into .codex/skills.

5. Validate local skills.

   • Use scripts/check_project_local_skills.py.
   • Confirm links point to real files and commands.
   • Confirm local skill bodies are short and repo-specific.
   • Use $subagent-review-orchestrator separately for .codex/agents generation; do not mix local skills and subagent files.

Validation

• Run scripts/suggest_project_local_skills.py <repo> --json before generating.
• Run scripts/generate_project_local_skills.py <repo> when generation is requested.
• Run scripts/check_project_local_skills.py <repo> after generation.
• Confirm existing local skills were preserved unless overwrite was explicitly requested.

Completion Criteria

• The repo has only useful project-local skills backed by actual artifacts.
• Generated skills point to repo-local docs/scripts and avoid generic plugin-scale instructions.
• Reusable harness logic remains in the plugin.