| name | adjust-agent |
| description | Apply best-practice improvements to an existing agent — runs /review-agent to find issues, then proposes exact before/after changes to CLAUDE.md, skills, and Trinity files and applies the approved ones. |
| argument-hint | [path to agent] [what to improve] |
| disable-model-invocation | false |
| user-invocable | true |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill |
| metadata | {"version":"1.2","created":"2026-04-04T00:00:00.000Z","updated":"2026-06-18T00:00:00.000Z","author":"Ability.ai","changelog":["1.2: Apply Documentation Coherence fixes — generate missing README/ARCHITECTURE/TARGET-ARCHITECTURE + /reconcile-docs, fix descriptive targets, flag prescriptive-source drift","1.1: Compose /review-agent for the audit instead of an inline rubric (Composition Rule — single-sourced); add Skill to allowed-tools; add composition-aware fix guidance","1.0: Initial version"]} |
Adjust Agent
ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. adjust-agent vX.Y — recent: <summary>. Then proceed.
Transition an existing agent to a better state. This is the apply half of the review/adjust pair: it invokes /review-agent (a read-only audit) to find issues, then proposes exact before/after diffs, gets approval, and applies them. Works like /adjust-playbook, but for the agent as a whole.
When to Use
- User says "review this agent" or "improve my agent"
- User says "add a dependency graph" or "set up schedules"
- User says "make this agent Trinity-ready"
- After scaffolding an agent and wanting to harden it
- Periodic health check on an established agent
Step 1: Locate and Read the Agent
If $0 (path) provided, use it. Otherwise, assume current working directory.
Verify it's an agent:
ls CLAUDE.md 2>/dev/null && ls -d .claude/skills 2>/dev/null
If CLAUDE.md doesn't exist, ask for the correct path.
Read all agent artifacts (skip any that don't exist — their absence is itself a finding):
CLAUDE.mdREADME.md, ARCHITECTURE.md, TARGET-ARCHITECTURE.mdtemplate.yaml.env.example.gitignore.mcp.json.template or .mcp.json- All
SKILL.md files:
find .claude/skills -name "SKILL.md" 2>/dev/null
- Any subagents:
ls .claude/agents/*.md 2>/dev/null
- Top-level file listing:
ls -la
Parse and display the agent's current state:
## Current Agent: [name]
**Identity**: [one-line summary or "not defined"]
**Skills**: [count] — [list names]
**Dependency Graph**: [present / missing]
**Docs**: README [✓/✗] · ARCHITECTURE [✓/✗] · TARGET-ARCHITECTURE [✓/✗]
**Recommended Schedules**: [present / missing]
**Guidelines**: [count or "none"]
**Trinity Ready**: [yes / partially / no]
Step 2: Determine What to Change
From $ARGUMENTS or conversation context, identify what the user wants. If the user asked for a general review, invoke /review-agent for the full audit (Step 3). If they asked for something specific, scope /review-agent to that focus area.
| Change Type | Examples |
|---|
| Full review | "review this agent", "check best practices" |
| Add dependency graph | "add artifact dependencies", "set up the graph" |
| Add schedules | "recommend schedules", "which skills should be scheduled" |
| Improve identity | "flesh out the identity section", "improve CLAUDE.md" |
| Add guidelines | "add behavioral rules", "set up guidelines" |
| Fix skill docs | "sync skills with CLAUDE.md", "document the skills" |
| Doc coherence | "add architecture docs", "add a README", "the docs are out of date", "install /reconcile-docs" |
| Trinity readiness | "make this Trinity-ready", "prepare for deployment" |
| Skill quality | "review skill permissions", "check the skills" |
If unclear, ask:
Use AskUserQuestion:
- Question: "What would you like to improve about this agent?"
- Header: "Adjust Agent"
- Options:
- Full review — Check everything against best practices
- Add artifact dependency graph
- Add recommended schedules
- Improve CLAUDE.md structure (identity, capabilities, guidelines)
- Documentation coherence (README, ARCHITECTURE, TARGET-ARCHITECTURE, /reconcile-docs)
- Trinity readiness (template.yaml, .env, .gitignore)
- Skill quality review
- Other (describe)
Step 3: Audit (via /review-agent)
Invoke /review-agent to produce the findings — it is the single source of truth for the audit rubric (identity, capabilities, dependency graph, schedules, guidelines, skill quality, composition integrity, Trinity readiness, hygiene). Pass the agent path and, for a scoped request, the focus area:
Invoke `/review-agent [path] [focus area]`
Use its scorecard and findings table as the input to Step 4. Do not re-audit by hand — if a check seems missing, add it to /review-agent (so every caller benefits), not here.
Step 4: Propose Changes
For each IMPROVE or MISSING finding from /review-agent, propose a specific change with exact before/after. Follow the adjust-playbook pattern.
## Proposed Changes to [Agent Name]
### Change 1: [Area] — [What changes]
**Status**: MISSING → adding / IMPROVE → updating
Before:
[current content, or "Section does not exist"]
After:
[exact new content to insert or replace]
**File**: [which file is being changed]
**Impact**: [what this enables or fixes]
---
### Change 2: [Area] — [What changes]
...
---
### Unchanged
Everything else remains the same:
- [list preserved sections/files]
Ordering: Present changes from highest to lowest impact:
- Structural gaps (missing sections in CLAUDE.md)
- Completeness (dependency graph, schedules)
- Quality (skill permissions, guidelines)
- Polish (hygiene, docs alignment)
Fix guidance for the non-obvious areas:
- Dependency graph (MISSING) — draft a complete
artifacts: + sync_skills: block from the agent's actual files and skills.
- Schedules (MISSING) — propose cadences by task type: monitoring/health → 15m–1h; sync/update → 1–6h or daily; reports/summaries → daily/weekly; cleanup → weekly. Default
enabled: false.
- Composition findings — for skill-internal fixes (missing
Skill tool, broken invoke target, cycles, inlined logic), hand off to /agent-dev:adjust-playbook rather than rewriting the SKILL.md's logic here.
- Documentation coherence (MISSING/DRIFT) — for missing docs, generate them from the templates in
/create-agent:create STEP 9 (README.md, ARCHITECTURE.md, TARGET-ARCHITECTURE.md) and install the /reconcile-docs skill (STEP 10); register all three in the dependency graph. For drift, respect the graph's direction: fix descriptive targets (README.md, ARCHITECTURE.md) to match reality, move shipped items from TARGET-ARCHITECTURE.md into ARCHITECTURE.md, and only flag drift in prescriptive sources (CLAUDE.md, TARGET-ARCHITECTURE.md) for the user — don't rewrite intent. Where an agent already has /reconcile-docs, prefer running it over re-deriving the checks here.
Step 5: Confirm
Use AskUserQuestion:
- Question: "Which changes should I apply?"
- Header: "Apply Changes"
- Options:
- Apply all — Make all proposed changes
- Let me pick — Select specific changes by number
- Modify proposal — Adjust a change before applying
- Cancel — No changes
If the user picks "Let me pick", list changes numbered and let them select.
If the user picks "Modify proposal", ask what to adjust about the specific change, re-propose, and confirm again.
Step 6: Apply Changes
For each approved change:
- Find the exact text to replace (or insertion point for new sections)
- Apply with the Edit tool (or Write for new files)
- Verify the edit succeeded by reading the changed region
Apply changes to one file at a time. If multiple changes target the same file, apply them top-to-bottom to avoid offset issues.
Step 7: Verify and Report
Read each modified file and confirm changes applied correctly.
## Agent Updated: [Name]
Changes applied:
- [x] [Change 1 summary]
- [x] [Change 2 summary]
- [ ] [Skipped change — reason]
### Before / After
| Area | Before | After |
|------|--------|-------|
| Identity | [status] | [status] |
| Capabilities | [status] | [status] |
| Dependency Graph | [status] | [status] |
| Schedules | [status] | [status] |
| Guidelines | [status] | [status] |
| Skill Docs | [status] | [status] |
| Skill Quality | [status] | [status] |
| Doc Coherence | [status] | [status] |
| Trinity Ready | [status] | [status] |
| Hygiene | [status] | [status] |
### Remaining Items
[List anything still at IMPROVE or MISSING — can be addressed with another `/adjust-agent` run]
Audit Checklist Reference
The audit rubric lives in /review-agent — the single source of truth. This skill consumes its findings and applies the approved fixes; it does not re-define the checks.
Related Skills
