skill-gap-observer

A meta-skill for Codex that detects repeated workflow friction and proposes new skills only when evidence supports a real speed/quality/reliability gain.

Why

Most skill collections drift into noise. skill-gap-observer adds strict gates so new skills are created only when justified by repeated problems and measurable impact.

Key Behavior

• Mandatory post-checkpoint on substantial tasks.
• In-the-moment Fix Now tactical suggestion.
• Candidate lifecycle: new, update, merge, kill, promote.
• Impact scoring:
  • impact_score = 0.5*time_loss + 0.3*rework + 0.2*defect_risk
  • each component is 0..5
• Promotion to create only when gates pass.
• Human approval gate: even with Verdict: create, no auto-creation.
• Post-creation ROI review after 5 uses.

Install

1. Copy skill files into your Codex global skills directory:

mkdir -p "$HOME/.codex/skills/skill-gap-observer/agents"
cp skills/skill-gap-observer/SKILL.md "$HOME/.codex/skills/skill-gap-observer/SKILL.md"
cp skills/skill-gap-observer/agents/openai.yaml "$HOME/.codex/skills/skill-gap-observer/agents/openai.yaml"

2. Add project-level policy snippet from templates/AGENTS.skill-gap-observer.md into your project AGENTS.md.

3. Start a new chat/session so skill list refreshes.

Files

• Skill definition: skills/skill-gap-observer/SKILL.md
• UI metadata: skills/skill-gap-observer/agents/openai.yaml
• Candidate registry template: docs/skill-candidate-registry.md
• AGENTS integration snippet: templates/AGENTS.skill-gap-observer.md
• Example runs:
  • docs/examples/example-do-not-create.md
  • docs/examples/example-create-proposal.md

Usage Contract

Every observer report should include:

1. Observation
2. Evidence
3. Fix Now
4. Impact Score
5. Why Existing Skills Are Insufficient
6. Proposed Skill (or N/A)
7. Expected Gain
8. Complexity Risk
9. Candidate Status
10. Verdict

Versioning

Current version: v1.0.0 (see VERSION and CHANGELOG.md).