Claude Skill

self-improve

Capture durable user feedback into the governing skill/doc, or propose creating a new skill when no suitable one exists, so future sessions don't repeat the mistake. Use when the user rejects, reverts, or overrides the agent's output or approach on something a skill/doc covers or

LLM Mart · 0 points · 11 views 0 listing impressions 0 install-command copies
Download eai-org-agent-toolkit-skills_self-improve-d79feee.zip · 4 KB

Install

skills CLI npx skills add https://github.com/eai-org/agent-toolkit/tree/main/skills/self-improve
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install eai-org-agent-toolkit@llmmart
Git git clone https://github.com/eai-org/agent-toolkit.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole eai-org/agent-toolkit collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Self-improve

Suggest durable improvements to the skill, doc or check that should have steered the agent, so the next session gets it right without being told again — and apply them only after the user approves. The skill proposes; the user stays in control of every change. Three ways in:

  • Manual — the user invokes /self-improve to deliberately improve a skill or doc.
  • Self-triggered — the agent notices it was corrected on something a skill, doc or check governs (or should). Don't silently correct and move on, but don't derail the task either: note the lesson, finish what the user asked for, and offer to persist it at the next natural breakpoint.
  • Driven by another skill — a caller hands over lessons already phrased as durable guidance (directly, through its launch command pasted by the user, or to a subagent it spawns per delegate.md), sometimes with all or part of a target it settled with the user (scope, form, path — possibly a new file or a merge into an existing one). Skip step 1; skip step 2 for a lesson whose target the caller settled fully, run it for the rest keeping what the caller settled — its Mechanical lesson bullet and new-doc indexing requirement always apply. Several lessons at once → first propose their placement as one table, each lesson with its doc, existing or new; then draft + apply, lessons sharing a target as one diff.

"Skill/doc" means any standing instruction: a SKILL.md, AGENTS.md/CLAUDE.md, a coding-standards or convention doc, a rules file — anything that guides future agents. A "check" (lint rule, hook, CI job) enforces one mechanically and is not a skill/doc.

Hard rules

  • Confirm before applying. The skill's job is to suggest, never to change text on its own. Never edit a skill, doc or check without the user's explicit go-ahead on the concrete change — present it as a diff and apply only on approval, whether the user invoked the skill or the agent self-triggered — except under Autoaccept, below. State plainly whether a change is not yet applied (awaiting approval) or already applied (and where), so the user never has to ask.
  • Editing any skill/doc → always route the write through one of two skills to keep it compact; never edit it directly. A SKILL.md goes through compact-skill-creator; any other doc (rule, AGENTS.md/CLAUDE.md, convention doc) goes through compact-docs-writer. Actually invoke the skill and follow its workflow before drafting or applying; reading it, applying its principles by hand, or naming it after a direct edit does not count. A check is edited directly.

Autoaccept

The word autoaccept, in the invocation or a caller's brief, is the go-ahead given in advance: each lesson's target (the placement table included) and edit take the agent's own recommendation and are applied without the diff being confirmed (the compaction skills' present-and-confirm step included), each reported with the file it changed or that already covers it. Still put to the user (in a subagent, reported blocked): a lesson that reverses an existing rule, one needing a new target (step 2), and any placement the agent is unsure of.

Recognize a persistable correction (self-trigger)

Signals the agent was corrected in a way worth persisting: the user rejects or reverts a choice ("no, do X instead"), states a standing preference ("we always…", "never…"), or redirects an action the agent took under a skill or doc.

Only persist a durable lesson — one that generalizes and will recur. Skip one-off, task-specific tweaks that won't apply next time; persisting those pollutes the docs. Whenever unsure whether it generalizes, ask the user.

Workflow

  1. Capture the lesson. State, in one line, the general rule the feedback implies — not the surface incident ("Mock external HTTP in unit tests," not "the agent mocked the wrong call").
  2. Locate the target. Settle scope first: would the lesson hold in another project? No → a project doc, rule or wrapper, never a shared generic skill. Yes → the governing skill or doc, shared ones included, edited at its canonical source when the installed copy is a symlink or sync — the proposal says so. Find which skill/doc governs this action (search skills, AGENTS.md/CLAUDE.md, convention docs); when the repo defines a doc-placement guide (e.g. .agents/docs/README.md), follow it for locating and creating targets. If one exists, it's the target — and if that rule already existed yet failed to steer the agent, the discoverability gap is the lesson, not a no-op: don't stop at "the rule exists." Diagnose why it didn't fire (buried, in a doc the agent wouldn't open for this action, scoped or worded too narrowly, or unenforced) and fix that root cause: surface it where the agent looks, tighten its scope, cross-reference it, or enforce it mechanically. If none fits, propose a new target and ask before drafting: a check for a mechanical lesson (below), a new skill for a recurring workflow, a new rule for a standing constraint, or the most fitting doc otherwise; a new doc comes with its entry-file index line and read-when hook, or nothing ever loads it. Ask whenever unsure.
    • Mechanical lesson (a banned API, an import shape, a file location: any fixed pattern) → propose a deterministic check over prose; the check is declined, or no tooling can host it (the proposal says so) → write the rule. Read the repo's check scripts and CI first: wire or repair an existing check rather than add one.
    • Place by context cost. Always-loaded docs (AGENTS.md/CLAUDE.md) hold mostly pointers; a rule that matters only when reviewing goes in a review-time doc, not implementation context.
  3. Draft the edit. Write the rule into the target as the least text that fully captures it: agent-agnostic ("the agent", never a vendor name), no process narration, no restating — a real durable instruction. Prefer tightening or extending an existing rule over appending a new one. If the lesson reverses an existing rule, surface that explicitly — show the old rule, the feedback, and the proposed replacement — and never overwrite it silently; the contradiction may mean the feedback is context-specific, not a true reversal. A check is drafted outside the repo, with its proof: run it on a reproduction of the mistake (must fail) and on the corrected case (must pass), both results in the proposal; one that cannot run here is labelled untested.
  4. Apply the edit. Route the write per the Hard rules — SKILL.md → compact-skill-creator, any other doc → compact-docs-writer, a check → edited directly — presenting a diff and applying only on approval, Autoaccept aside. Done when every handed-over or captured lesson is applied, declined by the user, reported as already covered or still put to the user (Autoaccept), each named in the closing message.
Files (agent-toolkit)
  • delegate.md 1.8 KB
    Loading…
  • SKILL.md 7.5 KB
    ---
    name: self-improve
    description: Capture durable user feedback into the governing skill, doc or check, or propose creating a new skill when no suitable one exists, so future sessions don't repeat the mistake. Use when the user rejects, reverts, or overrides the agent's output or approach on something a skill, doc or check covers or should cover, and when manually invoked to improve or create guidance.
    allowed-tools: Read, Write, Edit, Glob, Grep, Bash
    license: MIT
    metadata:
      version: "1.14"
    ---
    
    # Self-improve
    
    **Suggest** durable improvements to the skill, doc or check that should have steered the agent,
    so the next session gets it right without being told again — and apply them only after the user
    approves. The skill proposes; the user stays in control of every change. Three ways in:
    
    - **Manual** — the user invokes `/self-improve` to deliberately improve a skill or doc.
    - **Self-triggered** — the agent notices it was corrected on something a skill, doc or check
      governs (or should). Don't silently correct and move on, but don't derail the task either: note
      the lesson, finish what the user asked for, and offer to persist it at the next natural
      breakpoint.
    - **Driven by another skill** — a caller hands over lessons already phrased as durable guidance
      (directly, through its launch command pasted by the user, or to a subagent it spawns per
      [delegate.md](delegate.md)), sometimes with all or part of a target it settled with the user
      (scope, form, path — possibly a new file or a merge into an existing one). Skip
      step 1; skip step 2 for a lesson whose target the caller settled fully, run it for the rest
      keeping what the caller settled — its Mechanical lesson bullet and new-doc indexing requirement
      always apply. Several lessons at once → first propose their placement as one table, each lesson
      with its doc, existing or new; then draft + apply, lessons sharing a target as one diff.
    
    "Skill/doc" means any standing instruction: a `SKILL.md`, `AGENTS.md`/`CLAUDE.md`, a
    coding-standards or convention doc, a rules file — anything that guides future agents. A "check"
    (lint rule, hook, CI job) enforces one mechanically and is not a skill/doc.
    
    ## Hard rules
    
    - **Confirm before applying.** The skill's job is to **suggest**, never to change text on its own.
      Never edit a skill, doc or check without the user's explicit go-ahead on the concrete change —
      present it as a diff and apply only on approval, whether the user invoked the skill or the agent
      self-triggered — except under Autoaccept, below. State plainly whether a change is not yet
      applied (awaiting approval) or already applied (and where), so the user never has to ask.
    - **Editing any skill/doc → always route the write through one of two skills to keep it compact;
      never edit it directly.** A `SKILL.md` goes through
      [compact-skill-creator](../compact-skill-creator/SKILL.md); any other doc (rule,
      `AGENTS.md`/`CLAUDE.md`, convention doc) goes through
      [compact-docs-writer](../compact-docs-writer/SKILL.md). Actually invoke the skill and follow its
      workflow *before* drafting or applying; reading it, applying its principles by hand, or naming it
      after a direct edit does not count. A check is edited directly.
    
    ## Autoaccept
    
    The word `autoaccept`, in the invocation or a caller's brief, is the go-ahead given in advance:
    each lesson's target (the placement table included) and edit take the agent's own recommendation
    and are applied without the diff being confirmed (the compaction skills' present-and-confirm step
    included), each reported with the file it changed or that already covers it. Still put to the user
    (in a subagent, reported `blocked`): a lesson that reverses an existing rule, one needing a new
    target (step 2), and any placement the agent is unsure of.
    
    ## Recognize a persistable correction (self-trigger)
    
    Signals the agent was corrected in a way worth persisting: the user rejects or reverts a choice
    ("no, do X instead"), states a standing preference ("we always…", "never…"), or redirects an action
    the agent took under a skill or doc.
    
    **Only persist a *durable* lesson** — one that generalizes and will recur. Skip one-off,
    task-specific tweaks that won't apply next time; persisting those pollutes the docs.
    Whenever unsure whether it generalizes, ask the user.
    
    ## Workflow
    
    1. **Capture the lesson.** State, in one line, the general rule the feedback implies — not the
       surface incident ("Mock external HTTP in unit tests," not "the agent mocked the wrong call").
    2. **Locate the target.** Settle scope first: would the lesson hold in another project? No → a
       project doc, rule or wrapper, never a shared generic skill. Yes → the governing skill or doc,
       shared ones included, edited at its canonical source when the installed copy is a symlink or
       sync — the proposal says so. Find which skill/doc governs this action (search skills,
       `AGENTS.md`/`CLAUDE.md`, convention docs); when the repo defines a doc-placement guide (e.g.
       `.agents/docs/README.md`), follow it for locating and creating targets. If one exists, it's the
       target — and if that rule already existed yet failed to steer the agent, the discoverability gap
       *is* the lesson, not a no-op: don't stop at "the rule exists." Diagnose why it didn't fire
       (buried, in a doc the agent wouldn't open for this action, scoped or worded too narrowly, or
       unenforced) and fix that root cause: surface it where the agent looks, tighten its scope,
       cross-reference it, or enforce it mechanically. If none fits, propose a new target and ask
       before drafting: a check for a mechanical lesson (below), a new skill for a recurring workflow,
       a new rule for a standing constraint, or the most fitting doc otherwise; a new doc comes with its
       entry-file index line and read-when hook, or nothing ever loads it. Ask whenever unsure.
       - **Mechanical lesson** (a banned API, an import shape, a file location: any fixed pattern) →
         propose a deterministic check over prose; the check is declined, or no tooling can host it
         (the proposal says so) → write the rule. Read the repo's check scripts and CI first: wire or
         repair an existing check rather than add one.
       - **Place by context cost.** Always-loaded docs (`AGENTS.md`/`CLAUDE.md`) hold mostly pointers;
         a rule that matters only when reviewing goes in a review-time doc, not implementation context.
    3. **Draft the edit.** Write the rule into the target as the least text that fully captures it:
       agent-agnostic ("the agent", never a vendor name), no process narration, no restating — a real
       durable instruction. Prefer tightening or extending an existing rule over appending a new one.
       If the lesson **reverses** an existing rule, surface that explicitly — show the old rule, the
       feedback, and the proposed replacement — and never overwrite it silently; the contradiction may
       mean the feedback is context-specific, not a true reversal. A check is drafted outside the
       repo, with its proof: run it on a reproduction of the mistake (must fail) and on the corrected
       case (must pass), both results in the proposal; one that cannot run here is labelled untested.
    4. **Apply the edit.** Route the write per the Hard rules — `SKILL.md` → compact-skill-creator, any
       other doc → compact-docs-writer, a check → edited directly — presenting a diff and applying only
       on approval, Autoaccept aside. Done when every handed-over or captured lesson is applied,
       declined by the user, reported as already covered or still put to the user (Autoaccept), each
       named in the closing message.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.