AGENTS.md

1# AGENTS
2 
3## Start of Session
4 
5- Read SOUL.md for identity alignment.
6- Read the skill authoring guides for the relevant skill type.
7- Check team inbox for assignments from meta-lead (these take priority over self-directed work).
8 
9## Workflow
10 
11### 1. Check for Assigned Work
12 
13Review any tasks assigned by meta-lead. These are pre-triaged and should be addressed first:
14- P2 assignments: Cross-skill conflicts requiring immediate resolution.
15- P3 assignments: Drift alerts, maturity gaps, or tool baseline issues.
16- P4 assignments: Low-health or orphaned skills identified via graph analysis.
17 
18### 2. Audit Skills Using Available Data
19 
20When self-directing (no pending assignments), gather data from multiple sources:
21 
22**From prompt-manager graph:**
23- `prompt-manager graph health --type skill` — Sort by lowest health to find underperformers.
24- `prompt-manager graph orphaned-skills` — Skills no agent references (candidates for adoption or retirement).
25- `prompt-manager graph cliless-skills` — Skills that could benefit from CLI promotion.
26- `prompt-manager graph popular --type skill` — Most-referenced skills (high-leverage improvement targets).
27- `prompt-manager graph node <skill-id>` — Inspect a specific skill's connections and health breakdown.
28 
29**From development-toolchain-validator (when available):**
30- `development-toolchain-validator report --conflicts` — Cross-skill contradictions to resolve.
31- `development-toolchain-validator report --maturity` — Skills too vague to define structural expectations.
32- `development-toolchain-validator report --drift [--skill <id>]` — Skills whose content changed since last validation.
33 
34### 3. Prioritize Targets
35 
36Rank targets by severity and compound impact:
371. **Cross-skill conflicts** — Actively corrupting agent output. Resolve immediately.
382. **High-usage low-health skills** — Cross-reference `popular` with `health` for maximum leverage.
393. **Drifted skills** — Content changed, expectations may be stale.
404. **Low-maturity skills** — Too vague to validate. Candidates for tightening with concrete, verifiable instructions.
415. **Orphaned skills** — Unreferenced. Candidates for adoption into relevant agents or retirement.
426. **CLI promotion candidates** — Skills with operational instructions that should become CLI contracts.
43 
44### 4. Optimize
45 
46- Rewrite or improve skills following the appropriate authoring guide.
47- For conflicts: identify the contradiction, determine the correct guidance, update both skills.
48- For low maturity: add concrete, verifiable instructions that enable structural expectations.
49- Validate every change against `skill-validation` criteria.
50 
51### 5. Report
52 
53- Report changes to meta-lead with before/after comparisons.
54- Include expected compound impact (which agents and teams benefit).
55- Track health scores after changes to validate improvement.
56 
57## Skills
58 
59- `prompt-manager skill read skill-principles` — Universal requirements.
60- `prompt-manager skill read skill-authoring` — Steer skill creation guide.
61- `prompt-manager skill read skill-authoring-meta` — Meta skill creation guide.
62- `prompt-manager skill read skill-authoring-practice` — Practice skill creation guide.
63- `prompt-manager skill read skill-authoring-tools` — Tools skill creation guide.
64- `prompt-manager skill read skill-authoring-search` — Search skill creation guide.
65- `prompt-manager skill read skill-validation` — Quality criteria.
66- `prompt-manager skill read skill-improvement-suggestions` — Improvement methodology.
67 
68## Coordination
69 
70- Receive priority-ranked assignments from meta-lead.
71- Report skill changes with before/after comparisons and impact analysis.
72- Track effectiveness ratings after changes to validate improvements.
73- Coordinate with agent-optimizer when skill changes affect agent configurations.
74