notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/agent-upgrade.md
View on GitHub---
description: "5-phase agent/skill improvement: AUDIT, DIFF, PLAN, IMPLEMENT, RE-EVALUATE."
user-invocable: false
argument-hint: "<agent-or-skill-name>"
allowed-tools:
- Read
- Bash
- Glob
- Grep
- Agent
- Edit
- Write
routing:
triggers:
- upgrade agent
- improve agent
- agent upgrade
- fix agent quality
- align agent to template
pairs_with:
- agent-evaluation
- system-upgrade
complexity: Medium
category: meta
---
# Agent Upgrade Pipeline
## Overview
This skill upgrades one agent or skill through a phased pipeline. Use direct review and relevant repository checks by default. Run the scoring steps and score fields below only when the user requests evaluation or a specific uncertainty warrants it; otherwise record checks and findings in their place. Required tests still apply.
It is a **bottom-up** quality mechanism — triggered when a specific component needs
improvement — complementing the **top-down** `system-upgrade` pipeline that handles
multi-component changes driven by external events.
---
## Instructions
### Phase 1: AUDIT
**Goal**: Establish a baseline quality score for the target agent or skill.
**Step 1**: Identify the target file from the user's input.
```
# Common target patterns:
skills/programming/programming/references/golang-general.md
skills/programming/programming/references/python-general.md
skills/programming/programming/SKILL.md
```
Repo agents are retired (plan 009): a retired agent name resolves to its skill reference. If the user names an agent or reference without a path, resolve it:
```bash
ls skills/*/*/references/ | grep [name]
ls skills/ | grep [name]
ls private-agents/ | grep [name] # private overlay agents only
```
**Step 2**: Call the Skill tool with `toolkit` and run its Agent Evaluation mode. Evaluate the target file to get the baseline score (0–100) and grade (A/B/C/F).
For ordinary maintenance, record the existing behavior, relevant requirements, and checks instead of a model score.
**Step 3**: Read the telemetry for this agent:
```bash
python3 ~/.claude/scripts/learning-db.py route-stats --by agent 2>/dev/null || echo "No routing telemetry available"
```
A high error rate names a gap worth fixing.
**Step 4**: Check for staleness markers in the target file:
- Missing frontmatter fields: `context`, `model`, `user-invocable` (for skills)
- Operator Context section absent or incomplete (no Hardcoded/Default/Optional subsections)
- Version references to deprecated patterns
- Hook event types that have been superseded
**Output**:
```
AUDIT COMPLETE
==============
Target: [file path]
Baseline: [score]/100 ([grade])
Known gaps detected:
- [gap 1]
- [gap 2]
...
Retro candidates: [N found | none]
```
**Gate**: Baseline behavior and checks recorded; score included when evaluation applies. Proceed to Phase 2.
---
### Phase 2: DIFF
**Goal**: Gap analysis against current patterns, templates, and peers.
**Step 1**: Compare target against the agent template structure. Read the template:
```bash
# Read the agent template
cat skills/meta/toolkit/references/skill-creator/agent-template.md | head -50
```
Check for required sections. For agents:
- Frontmatter with `routing:` block (triggers, pairs_with, complexity, category)
- Operator Context with all three subsections (Hardcoded, Default, Optional)
- Error Handling section
For skills:
- Frontmatter with `agent:`, `allowed-tools:`, `user-invocable:`
- Operator Context section
- Phase-by-phase instructions with gates
- Error Handling section
**Step 2**: Assess Operator Context completeness:
| Subsection | Present? | Complete? |
|------------|----------|-----------|
| Hardcoded Behaviors | ? | ? |
| Default Behaviors | ? | ? |
| Optional Behaviors | ? | ? |
**Step 3**: Turn the Phase 1 telemetry and registry findings into candidate edits. For each finding:
- Note the pattern or behavior the agent lacked
- Identify where in the target it belongs (new hardcoded behavior, key pattern, error handling rule)
**Step 4**: Peer consistency check. Find 2–3 agents in the same category:
```bash
# For a Go agent, compare against other Go agents
grep -l "golang\|go\b" agents/*.md | grep -v [target] | head -3
```
Read peer Operator Context and structure. Note patterns present in peers but missing in target.
**Output**: Diff report — categorized list of gaps:
```
DIFF REPORT
===========
Target: [file path]
Missing Sections:
- [section name]: [description of what's needed]
Outdated Patterns:
- [pattern]: [current form] → [correct form]
Operator Context Gaps:
- [missing behavior]: [description]
Telemetry and Registry Findings:
- [finding]: → [where it belongs in the agent]
Peer Inconsistencies:
- [pattern in peers]: [missing from target]
```
**Gate**: Diff report produced. Proceed to Phase 3.
---
### Phase 3: PLAN
**Goal**: Present prioritized improvements and confirm they fit the authorized scope.
**Step 1**: Rank all gaps from Phase 2 by tier:
| Tier | Criteria | Examples |
|------|----------|---------|
| **Critical** | Broken structure, missing required sections | No Operator Context, broken frontmatter |
| **Important** | Missing patterns that meaningfully affect quality | Missing Hardcoded behaviors, an unaddressed telemetry or registry finding |
| **Minor** | Style alignment, peer consistency, optional fields | Missing optional frontmatter field, peer wording alignment |
**Step 2**: Present the ranked plan to the user:
```
AGENT UPGRADE PLAN
==================
Target: [file path]
Baseline: [score]/100 ([grade])
Proposed Improvements (Ranked):
CRITICAL (must fix):
1. Add Operator Context section — Hardcoded/Default/Optional subsections absent [~20min]
2. Add Error Handling section — 3 unhandled failure modes identified [~15min]
IMPORTANT (should fix):
3. Embed telemetry finding: "[finding summary]" → new Hardcoded behavior [~10min]
4. Remove out-of-policy frontmatter pin `model: sonnet` so the agent inherits (or pin `opus`) [~2min]
MINOR (nice to have):
5. Align "What This Agent CANNOT Do" wording to peer style [~5min]
Total: 5 improvements
Estimated quality delta: +12 to +18 points
Proceed with implementation? (or specify which items to include/exclude)
```
**Step 3**: Continue when the user already authorized these improvements. Ask only about uncovered changes or material scope changes. Honor plan-only and interactive requests; a stop request ends implementation.
**Gate**: Plan presented and implementation scope authorized. Proceed to Phase 4.
---
### Phase 4: IMPLEMENT
**Goal**: Apply the approved improvements to the target file.
**Step 1**: Read the current target file in full before making any edits. Never edit from memory. This prevents collisions when the file changes between Phase 3 and Phase 4.
**Step 2**: For each approved improvement, apply in order of tier (Critical first):
**For missing sections** (add from agent-template patterns):
- Operator Context: Add the three-subsection structure. Populate Hardcoded with behaviors that ARE enforced, Default with on-by-default behaviors, Optional with opt-in behaviors.
- Error Handling: Add 2–4 concrete error cases with Cause + Solution format.
**For telemetry and registry findings**:
- Add the finding as a new Hardcoded behavior (if it should always apply) or a new pattern/rule in the relevant section.
- Keep the finding's original specificity — a paraphrase into generic advice carries nothing. Embed only findings directly relevant to the target agent's domain.
**For outdated patterns**:
- Update to current convention. Reference the peer agents or template for the correct form.
**For peer inconsistencies**:
- Align to the majority pattern observed across peers. If peers themselves are inconsistent, align to the most recent or highest-scoring peer.
**Step 3**: Run positive framing validation on the modified agent or skill.
After applying all approved improvements, validate the target file's framing. Call the Skill tool with `joy-check`. Use instruction mode. This ensures that new or modified content uses positive framing per ADR-127.
Positive framing produces instructions agents act on rather than rules they work around.
If joy-check flags lines in the NEW content (content that was just added/modified):
- Fix those lines as part of this same implementation pass
- Do not flag pre-existing content that was not part of the upgrade scope
If joy-check flags lines in EXISTING content (not modified by this upgrade):
- Note them in the upgrade report but do not fix them (out of scope for this upgrade)
**Step 4**: Change the following only when the user explicitly directs it, because domain logic changes require deliberate user decision rather than opportunistic bundling:
- Routing triggers (`triggers:` frontmatter field)
- Domain coverage statements
- Core methodology or phase structure (for skills)
- Agent pairing recommendations (`pairs_with:`)
**Gate**: All approved items implemented. No pending items from the approved plan.
---
### Phase 5: RE-EVALUATE
**Goal**: Score the updated agent and compute quality delta.
**Step 1**: Call the Skill tool with `toolkit` and run its Agent Evaluation mode. Evaluate the modified file and record the after score and grade.
**Step 2**: Compute delta:
```
delta = after_score - baseline_score
```
**Step 3**: If delta is negative (regression):
- Show the exact diff of changes applied
- Report which change likely caused the regression
- Ask user whether to revert the specific change or proceed anyway
- Offer the revert path instead of applying it automatically, because the user may have context that justifies the regression
**Step 4**: Report upgrade completion:
```
UPGRADE COMPLETE
================
[agent-name or skill-name]
Before: [baseline_score] ([baseline_grade])
After: [after_score] ([after_grade])
Delta: +[N] points
Improvements applied: [N/N approved items]
Items applied:
✓ [improvement 1]
✓ [improvement 2]
○ [improvement N — skipped by user]
```
If the delta is positive, the upgrade is complete. If the delta is zero or negative and the user has not already acknowledged it, surface the regression report before closing.
**Gate**: Required checks pass and blocking findings are resolved. If evaluation was requested, report its result and resolve any material regression before closing.
---
## Error Handling
### Error: "agent-evaluation skill unavailable or errors out"
Cause: The `agent-evaluation` skill has a dependency issue or the target file is malformed.
Solution: Read the target file manually and apply the scoring rubric from the CLAUDE.md quality gates section (Structure 20pts, Operator Context 15pts, Error Handling 15pts, Reference Files 10pts, Validation Scripts 10pts, Content Depth 30pts). Produce a manual score. Note it as manually derived in the report.
### Error: "No routing telemetry found for this agent"
Cause: The agent has carried no routed dispatches, or telemetry is not populated in this environment.
Solution: Proceed on the evaluation baseline alone and note the gap in the diff report. An agent with zero routes over a long window is a retirement candidate, not just an upgrade candidate.
### Error: "Agent template not found in repository"
Cause: Template file not at expected path (`skills/meta/toolkit/references/skill-creator/agent-template.md`).
Solution: Use the highest-scoring agent (from recent agent-evaluation runs or MEMORY.md) as the de facto template for structural comparison. Note the substitution in the diff report.
### Error: "Regression detected in Phase 5 (delta is negative)"
Cause: One or more applied improvements reduced the evaluation score.
Solution: Show the diff, identify the likely culprit change, and ask the user whether to revert it. Keep rollback user-driven and proceed only after the user makes a decision.
### Error: "User approves plan but target file changes between Phase 3 and Phase 4"
Cause: Another process or agent modified the file during the gap.
Solution: Re-read the file before editing. If the baseline state has changed materially, re-run Phase 1–2 and re-present the plan.
---
## References
- [agent-evaluation](../../skills/meta/agent-evaluation/SKILL.md) - Objective scoring skill used in Phase 1 (baseline) and Phase 5 (re-evaluate)
- [system-upgrade](../system-upgrade/SKILL.md) - Top-down multi-component upgrade pipeline (complements this bottom-up single-agent pipeline)
- [agent-template](../../skill-creator/references/agent-template.md) - Structural template used for gap analysis in Phase 2
- [learning-db.py](../../scripts/learning-db.py) - Read-only CLI for routing telemetry (`route-health`, `route-stats`)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |