# Self Improving Agent > Meta-skill for making the agent self-improving. Covers updating AGENTS.md, creating new skills from repeated workflows, and deciding what to systematize. Invoke after completing tasks, when noticing repeated friction, or at session end. - Skill: `grail-computer/self-improving-agent` (Agent Skill) - Install (CLI): `npx skillmds@latest add grail-computer/self-improving-agent` - Raw SKILL.md: https://api.skillmd.com/api/skills/grail-computer/self-improving-agent/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: grail-computer (https://skillmd.com/u/grail-computer) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/grail-computer/self-improving-agent --- # Self-Improving Agent > **When to use this skill:** > > - After completing a significant task (post-task reflection) > - When you notice yourself repeating a multi-step workflow > - When a human corrects your behavior and you need to persist the correction > - When the codebase map in AGENTS.md is stale > - At the end of a working session --- ## Step 1: Diagnose What Needs Improving Ask yourself these questions after completing work: 1. **Did I wander?** Did I spend time searching for files that should have been in the codebase map? - → Update the **Codebase Map** in `AGENTS.md` 2. **Did I get corrected?** Did the human tell me to do something differently? - → Add the correction to **Local Norms**, **Guardrails**, or **Patterns & Gotchas** in `AGENTS.md` 3. **Did I repeat a workflow?** Did I follow a multi-step procedure that I've done before (or will likely do again)? - → Create a new **skill** (see Step 3 below) 4. **Did something surprise me?** Did I discover a gotcha, a deprecated API, or a non-obvious coupling? - → Add it to **Patterns & Gotchas** in `AGENTS.md` 5. **Is the AGENTS.md stale?** Do the norms, entry points, or conventions no longer match the actual codebase? - → Update the outdated sections now If none of these apply, no action is needed. Don't create artifacts for the sake of it. --- ## Step 2: Update AGENTS.md When updating `AGENTS.md`, follow these rules: ### Codebase Map Updates 1. Read the current map in `AGENTS.md`. 2. Use `find` or `ls` (not recursive full-tree) to see the actual top-level structure. 3. Update only the parts that have changed. Don't rewrite the whole map. 4. Focus on: entry points, directory roles, config files, test locations. ### Adding Norms or Guardrails 1. Write the rule as a **short, imperative statement** — one line if possible. 2. Place it in the correct section: - **Local Norms** → How to build, test, run, or style code in this repo - **Guardrails** → What the agent must NEVER do - **Patterns & Gotchas** → Non-obvious discoveries about the codebase 3. If a correction contradicts an existing entry, update the existing entry rather than adding a duplicate. ### Quality Checks - Keep entries concise. Agents read this every session — brevity compounds. - Remove placeholder/example entries (italicized) once real entries exist. - Don't add generic advice. Every entry should be **specific to this repo**. --- ## Step 3: Create a New Skill Use this procedure when you've identified a repeatable workflow worth capturing. ### Decision: Is This a Skill or an AGENTS.md Entry? ``` Is it a multi-step procedure with a clear output? → YES → Skill → NO → AGENTS.md entry Is it specific to HOW this repo works (norms, navigation)? → YES → AGENTS.md entry → NO → Skill Am I unsure? → Start as an AGENTS.md entry. Promote to skill if it grows. ``` ### Creating the Skill 1. **Choose a name.** Use a verb-noun pattern reflecting the job: `debug-ci`, `draft-release-notes`, `run-migration`, etc. 2. **Create the folder and file:** ``` skills//SKILL.md ``` 3. **Write the SKILL.md** with this structure: ```markdown --- name: description: --- # > **When to use:** ## Steps 1. 2. 3. ... ## Output Contract ``` 4. **Key principles for good skills:** - Frame around a **job to be done**, not a tool ("debug CI failure", not "use grep") - Make the **trigger** clear — when should an agent reach for this? - Define the **output contract** — what does "done" look like? - Include **examples of good output** as assets if helpful (put in `skills//examples/`) - Keep steps **imperative and specific** — avoid vague instructions 5. **Add the new skill to the skills table** in `AGENTS.md`: ```markdown | [](skills//SKILL.md) | | | ``` ### Adding Scripts or Assets to a Skill If a skill needs deterministic execution (not just LLM judgment), add scripts: ``` skills// ├── SKILL.md # The playbook (always required) ├── scripts/ # Helper scripts for deterministic steps │ └── validate.sh └── examples/ # Reference outputs showing "good" quality └── example-output.md ``` Reference these from SKILL.md: "Run `scripts/validate.sh` to verify the output." --- ## Step 4: Decide Scope — Repo-Local vs Global vs Shared ``` Does this skill only matter for THIS repo? → Keep it in skills/ within this repo (repo-local) Have I felt this pain in another repo too? → Promote to ~/.agent/skills// (machine-global) → Copy the skill folder there Does my team keep repeating this workflow? → Promote to a shared repo or registry (shared) → Move the skill folder into the team's shared skills repo ``` ### Promotion Checklist When promoting a skill from repo-local to global: 1. Remove any repo-specific paths or references from the SKILL.md. 2. Make the instructions generic enough for any project. 3. Test it works without the original repo's context. 4. Keep the repo-local version if it has repo-specific customizations. --- ## Step 5: Validate the Improvement After making any changes (AGENTS.md update or new skill): 1. **Re-read the updated file.** Does it read clearly? Would a fresh agent session benefit from it? 2. **Check for contradictions.** Does the new entry conflict with anything existing? 3. **Check for bloat.** Is this file getting too long? If AGENTS.md exceeds ~200 lines, consider: - Archiving old gotchas that are no longer relevant - Moving detailed procedures into skills - Summarizing verbose entries 4. **Commit the changes** with a clear message: ``` docs: update AGENTS.md with ``` or ``` feat: add skill for ``` --- ## Anti-Patterns to Avoid | ❌ Don't | ✅ Do Instead | | --------------------------------------------------- | ------------------------------------------------------------------------- | | Add generic advice ("write clean code") | Add repo-specific rules ("use `pnpm`, not `npm`") | | Create skills for one-off tasks | Create skills for tasks you'll do again | | Let AGENTS.md grow unbounded | Prune stale entries, move procedures to skills | | Write vague skill steps ("figure out what's wrong") | Write specific steps ("run `npm test`, read the first failing assertion") | | Create a skill around a tool | Create a skill around a job to be done | | Start with shared/global skills | Start repo-local, promote when pain repeats | --- ## Quick Reference: The Compounding Loop ``` Work on task ↓ Complete task ↓ Reflect: Did I wander? Get corrected? Repeat a workflow? Discover a gotcha? ↓ ├── Navigation miss → Update Codebase Map ├── Behavior correction → Add to Local Norms / Guardrails ├── Repeated workflow → Create a Skill ├── Surprise discovery → Add to Patterns & Gotchas └── Nothing notable → Move on ↓ Next task starts from a better baseline ``` > _"The most valuable skill is the habit of watching yourself work."_ > Each improvement makes future improvements easier. That's how agents compound.