Skip to content

Self-improving skills

How an agent's own work becomes new skills and memory with nobody authoring them, and the read-only verbs the loop reads through.

Every agent turns its own work into better skills + memory on a cheap-notice → strong-compose → age-out loop. A hook fires every ~10 turns and, on a small model, writes skill / memory candidates (an idea plus pointers into the session) to a local store. The nightly dream-cycle then follows each candidate's pointers with the read-only introspection verbs and composes the real SKILL.md or memory. Agent-composed skills age out on real usage, active → stale (30d) → archived (90d); hand-written ones are never touched.

The three stages, and steering the review model per agent

  • Notice (per turn, cheap). A turn-review Stop hook (claude) / agent_end extension (pi) fires every ~10 turns and, on a small model (skill_model, default claude-haiku-4-5; per-agent overridable, OpenRouter-friendly), proposes skill / memory candidates (an idea + pointers: session id, a verbatim grep anchor, files touched) into ~/.cache/agentctl/turn-review-candidates.jsonl. Detached, work-gated, recursion-guarded; never blocks the session.
  • Compose (nightly, strong). The dream-cycle reads the candidate store and, per candidate, follows the pointer with the read-only introspection verbs below (sessions grep, mem, skills, ws changes/search) to pull exactly the evidence it needs and compose the real SKILL.md / memory: random access, not a full-week re-scan.
  • Age out (the curator). Agent-composed skills are stamped created_by: agent; the dream-cycle ages only those active → stale (30d) → archived (90d) using live sessions grep for real usage. Hand-written skills are never touched. Usage, not a strict entry gate, controls bloat, so capture stays liberal.

Steer the review model per agent: agentctl agents set <name> skill_model <model> then apply. It's a model-only override on the agent's own account/key (like the cron model override): claude → CLAUDE_SKILL_MODEL (default claude-haiku-4-5, back-filled); pi → PI_SKILL_MODEL (no default: empty reviews on the agent's normal PI_MODEL, since a claude model id is meaningless on a Groq/OpenRouter provider). pi crons carry the same per-job override, PI_CRON_MODEL (the analog of claude cron's CLAUDE_CRON_MODEL).

Introspection verbs (read-only, JSON; self-scope, admin/agentd cross-agent)

Seven read-only verbs over an agent's own sessions, memory, skills, candidate store and workspace. Each agent may query itself, and an admin agent may query any agent.

agentctl sessions   <agent> grep <pattern> [--role …] [--tool …] [--since …]
agentctl sessions   <agent> perms [--lane <lane>] [--all]
agentctl mem        <agent> [--type …] [--grep <re>] [--since …]
agentctl skills     <agent> [--since …]
agentctl candidates <agent> [--kind skill|memory] [--status …] [--since …]
agentctl ws changes <agent> [--since …]
agentctl ws search  <agent> <query>

skills is runtime-aware per agent: it lists ~/.claude/skills/ for claude, ~/.pi/agent/skills/ for pi. Live grep, no pre-built index. Each agent may query itself; the admin agent (via the agentd read-proxy) may query any agent. That is the same layer the dream-cycle composes from, and how you watch what's being proposed fleet-wide (candidates).