self-improving-agent · grail-computer — Claude Code skill: what it does, how to install
Teaches an agent to diagnose friction, update project guardrails in AGENTS.md, and turn repeated multi-step workflows into standalone skills.
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a claude-codeWhat self-improving-agent does
The skill initiates a review routine whenever the model finishes a major chore or receives corrections from a developer. It checks whether the agent struggled to find files, then refreshes the codebase map inside AGENTS.md. Discovered quirks, broken patterns, or style adjustments land directly into guardrails and repository norms.
Repeated multi-step jobs become distinct assets. If a procedure has predictable outputs, the agent drafts a new playbook under skills/<skill-name>/SKILL.md and appends it to the project index. Deterministic validation scripts can live right alongside the instructions. Workflows stay scoped to the current repository until their utility spans across multiple projects.
Once AGENTS.md stretches beyond 200 lines, the agent must trim stale notes or relocate detailed sequences into standalone skills. Vague suggestions like writing clean code are prohibited. Only project-specific constraints belong in the file.
What it helps with
- record developer feedback and constraints directly into
AGENTS.md - turn repetitive development procedures into new modular skills
- refresh outdated directory maps and entry points in project documentation
- prune bloated memory files when documentation exceeds size limits
Example prompts for the agent
- We just finished this refactor. Run self-improving-agent to reflect on the session and update AGENTS.md.
- Extract the migration procedure we just ran into a reusable skill.
- Note my correction about using pnpm instead of npm in the guardrails section.
How to install self-improving-agent
1Skills CLI (Vercel)
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a claude-code2Manually: put the files in place
~/.claude/skills/self-improving-agent/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/self-improving-agent/
1Skills CLI (Vercel)
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a codex2Manually: put the files in place
.agents/skills/self-improving-agent/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a cursor2Manually: put the files in place
.cursor/skills/self-improving-agent/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Grail-Computer/Self-Improving-Agent self-improving-agent2Manually: put the files in place
.github/skills/self-improving-agent/SKILL.md1Skills CLI (Vercel)
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a gemini-cli2Platform CLI
gemini skills install https://github.com/Grail-Computer/Self-Improving-Agent --path skills/self-improving-agentManually: put the files in place
.devin/skills/self-improving-agent/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about self-improving-agent
How to install self-improving-agent in Claude Code?
Run npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a claude-code. The setup places the instructions at ~/.claude/skills/self-improving-agent/SKILL.md.
What does self-improving-agent do?
It guides the assistant through a structured reflection process after completing tasks or receiving user corrections. The agent logs repository norms into AGENTS.md and converts repeating multi-step jobs into new skills.
When does the agent write to AGENTS.md instead of creating a skill?
Repo-specific habits, testing commands, entry points, and forbidden behaviors go directly into AGENTS.md. Multi-step procedures that produce concrete deliverables get separated into dedicated files inside skills/.
Similar skills
All skills for Agent setup: memory, context, orchestration →self-improving-agent by other authors comes first.
