Slash Command: /apex:improve_skill

Purpose

Create a skill improvement proposal from a mistake, review, or failed test.

Output

13_skills/skill_refinery/improvement_proposals/

Inputs

• target (string, required): the entity being acted on (repo name, slice id, etc.)
• Source-of-truth files: see 19_truth_state/source_of_truth_ranking.yaml
• Relevant schemas: 26_schemas/

Preconditions

• Repo structure check passes (apex_structure_check.yml)
• python3 25_automation/registry_sync/sync_registries.py --check is green
• Caller has write access to 13_skills/skill_refinery/improvement_proposals/

Step-by-step

1. Load context

Compile a context packet via 42_context_compiler/compile_context.py for the appropriate persona (12_agents/personas/).

2. Validate inputs

• Required input fields present.
• Input matches the relevant schema in 26_schemas/.
• No conflicts with existing artifacts in 13_skills/skill_refinery/improvement_proposals/.

3. Author artifact

• Use the matching template in 14_templates/.
• Reference the active ADRs (04_architecture/adrs/) and skills (13_skills/active/).
• Write artifact to 13_skills/skill_refinery/improvement_proposals/ with a deterministic filename.

4. Update registries

• Run python3 25_automation/registry_sync/sync_registries.py --write to refresh the relevant *.registry.yaml.
• Add a row to 18_registry/change_ledger.yaml.

5. Update traceability

• If artifact is a spec/ADR/diagram/test/evidence/release, add a row to 18_registry/traceability.yaml.

6. Validate

• Schema-validate the new artifact.
• Run drift checkers under 25_automation/drift_checkers/.

7. Capture evidence

• Append an evidence packet to 23_evidence/evidence_packets/ referencing the new artifact.

Outputs

• Artifact in 13_skills/skill_refinery/improvement_proposals/
• Updated *.registry.yaml
• Change ledger row
• Optional evidence packet
• Optional drift report

Success criteria

• New artifact exists, validates against schema, is referenced from the appropriate registry, and CI continues to pass.

Failure modes

| Failure | Detection | Remediation | |---|---|---| | Schema mismatch | schema-validate CI gate | fix artifact to match schema | | Registry drift | registry-sync-check | sync_registries.py --write | | Missing prerequisite | structure-check fails | seed required directory/file | | Duplicate artifact id | author-time check | choose next free ID | | OneDrive sync collision | hash mismatch on rerun | re-run after sync settles |

Rollback

Revert the commit that introduced the artifact:

git revert <sha>
python3 25_automation/registry_sync/sync_registries.py --write

Example invocation

# Pseudocode — actual invocation is via the agent harness
/apex:improve_skill target=ATLAS

See also

• APEX_PROTOCOL.md
• 37_command_protocol/commands.registry.yaml
• 25_automation/