agentleFS
l-gevityl-gevity/l-gevity-skills/.agents/skills/continuous-improvement/SKILL.md

continuous-improvement

Skill88 starsChanged 3 days agoMITView on GitHub

Protocol for updating skills based on user feedback and root-cause analysis to prevent recurring mistakes. Use this skill when deciding HOW and WHEN to evaluate or update other agent skills.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 12 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When the subject is the skills themselves, optimize in this order:

    line 56
  2. Distinctive:

    Check whether validation can catch it: mirror sync, frontmatter, primer backlinks, output contract presence, owner/routing conflicts, or …

    line 62
  3. Very specific:

    Keep .agents/skills, .claude/skills, and the matching .documentation/READ-*.md primer aligned in the same change.

    line 67
  4. Very specific:

    Run python scripts/validate-skills.py.

    line 70
  5. Distinctive:

    Use this sequence when learning originates in a consumer project:

    line 75
  6. Distinctive:

    Update the one canonical generic owner in the skill library.

    line 81
  7. Distinctive:

    Update mirrors, primers, indexes, root routing guidance, and validation in the same library change.

    line 83
  8. Distinctive:

    Do not overwrite a generic library from a consumer tree or treat byte-identical vendored files as locally owned.

    line 89
  9. Very specific:

    When generating the actual update to the relevant SKILL.md file:

    line 124
  10. Distinctive:

    Actionable Constraints: Ensure new rules are testable, direct, scoped, and explicit about exceptions.

    line 126
  11. Distinctive:

    Review Sibling Skills: Check existing skills to ensure you are not creating an ownership conflict or duplicating the rule's primary …

    line 128
  12. Distinctive:

    Maintain Mirrors and Validate: keep mirrors, primers, and the index aligned as Optimization Mode steps 4–5 require.

    line 133
  13. Distinctive:

    Ensure the learning "sticks":

    line 139
  14. Distinctive:

    Verification: If applicable, add a unit test, lint rule, schema check, or perform an audit showing the previous mistake is now caught …

    line 141
  15. Distinctive:

    When applying this skill, emit:

    line 155

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Continuous Improvement Protocol (Meta-Learning)

This protocol governs the agent's meta-learning process (Kaizen). It ensures that SKILL files evolve organically, preventing recurring errors through systemic, root-cause adjustments, without growing bloated.

Core Directives

  1. Automation Before Prose: Before adding a manual instruction to a SKILL document, check whether the lesson can be encoded as a test, linter, schema, type, build gate, or template. Observe a new check failing without the rule before calling it enforced; a check never seen to fail is a hypothesis, not a safeguard. If automation is infeasible or too costly, record why and add the smallest useful prose rule.
  2. Density Over Volume: Prefer replacing, merging, or tightening existing rules before adding new ones. Prune only rules proven obsolete, contradicted, or owned elsewhere.
  3. Root-Cause Focus: Do not preserve a symptom as the rule. Trace the error to its root cause (e.g., misunderstood framework, missing boundary rule) and fix the most upstream reusable guidance.
  4. Single Owner, Explicit References: Keep each rule's primary authority in one SKILL. Other SKILLs may mention it briefly as a cross-reference when routing users to the owner would prevent misuse.
  5. Operationalize Before Broadening: For skill-library updates, add or extend validation, templates, or primer checks before broad prose changes. If prose is still needed, keep the rule at the owning SKILL and route siblings to it.
  6. Promote Before Repinning: When a consumer project proves a reusable lesson, update the canonical generic skill library first. Publish that revision, then repin the consumer; keep project facts in a local overlay.

When to use this skill

  • Triggered by user corrections, systemic failures, or regression triggers that are likely to recur beyond the current conversation (full catalogue in §1).
  • Triggered when the user asks to improve, optimize, prune, or audit the skill library itself.
  • Out of scope: This skill dictates the triggers, analysis, and mindset for updating SKILLs. It does NOT dictate the formatting/layout of the SKILLs (follow your project's skill-authoring conventions) nor does it define the architectural code rules themselves (see architecture-guidelines).

Skill-Library Optimization Mode

When the subject is the skills themselves, optimize in this order:

  1. Name the observed failure the change prevents — a correction, transcript, incident, or scenario. Preferred wording, or a request to extend or complete a skill, is not one; without it, return a proposal with an M verdict instead of editing.
  2. Check whether validation can catch it: mirror sync, frontmatter, primer backlinks, output contract presence, owner/routing conflicts, or template shape.
  3. Edit the owning SKILL.md only. Sibling skills get cross-references unless they must make a routing decision.
  4. Keep .agents/skills, .claude/skills, and the matching .documentation/READ-*.md primer aligned in the same change. If the skill's public role or trigger changed, update the README.md skill index too.
  5. Run python scripts/validate-skills.py. If no mechanical check can cover the lesson, record why in the output contract.

Consumer-to-Library Promotion

Use this sequence when learning originates in a consumer project:

  1. Capture the concrete failure, correction, or repeated successful pattern and its verification evidence in the consumer.
  2. Extract the smallest behavior that applies without the project name, private paths, roles, domain taxonomy, local commands, or provider assumptions.
  3. Update the one canonical generic owner in the skill library. Add a skill only when the capability has a distinct trigger, lifecycle, and output contract.
  4. Update mirrors, primers, indexes, root routing guidance, and validation in the same library change.
  5. Validate and publish the library revision.
  6. Repin or reinstall that revision in the consumer, then retain only its project profile and other domain-specific skills locally.

Do not overwrite a generic library from a consumer tree or treat byte-identical vendored files as locally owned. If a local emergency patch is unavoidable, mark it as temporary divergence with an upstream owner and remove it when the published fix is repinned.


1. Triggers for Learning

Initiate this protocol to examine and update existing SKILL.md files when encountering:

Trigger TypeScenario
CorrectionUser explicitly corrects an architectural pattern, approach, or rule.
RegressionA fix for one issue breaks another, indicating an undocumented system boundary.
New PatternA new, validated structural standard is successfully introduced to the codebase.
Systemic FailureThe same class of anti-pattern or fragile workaround is attempted repeatedly, or once with high blast radius.
Process BreakRecurring CI/CD failures or linter bottlenecks indicating a broken foundational rule.
Skill OptimizationUser asks to optimize, prune, audit, or increase efficiency of the skill library itself.

2. Analyze Root Cause

Determine the underlying reason before writing a new rule. Ask:

  • Missing/Ambiguous: Was the requirement undocumented, too broad, too absolute, or written with the wrong force?
  • Conflict: Did two SKILL rules contradict each other?
  • Ignored Rule: Was a rule clear but ignored due to lack of visibility in the file? Improve placement or wording before promoting it to a warning block.
  • Technical Constraint: Was the failure due to a misunderstood platform or framework behavior?

3. The Update Execution

When generating the actual update to the relevant SKILL.md file:

  • Actionable Constraints: Ensure new rules are testable, direct, scoped, and explicit about exceptions.
  • Review Sibling Skills: Check existing skills to ensure you are not creating an ownership conflict or duplicating the rule's primary authority.
  • Eliminate Outdated Logic: Replace or delete previous rules only when they contradict, overlap with, or are made obsolete by the new learning. Preserve useful exceptions and migration notes.
  • Maintain Mirrors and Validate: keep mirrors, primers, and the index aligned as Optimization Mode steps 4–5 require; extend the validator when a drift pattern can be detected mechanically.

4. Verification & Notification

Ensure the learning "sticks":

  • Verification: If applicable, add a unit test, lint rule, schema check, or perform an audit showing the previous mistake is now caught earlier or made less likely. Do not claim structural impossibility unless an enforced gate guarantees it. For skill-library changes, run python scripts/validate-skills.py. A changed decision rule is a behavioral hypothesis: record the originating miss as a scenario that fails before the change and passes after, and apply the new rule to the change itself before calling it ready.
  • Notify: Conclude the improvement sequence with a concise summary back to the user:

    "Updated [Skill/Test] to prevent [issue] by mandating [new practice]."

5. Output Contract

When applying this skill, emit:

Subject:        <skill / test / linter / schema / template>
Trigger:        <correction | regression | new pattern | systemic failure | process break | skill optimization>
Root cause:     <missing/ambiguous | conflict | ignored rule | technical constraint | ownership gap>
Owner:          <skill/test/linter/schema/template that should own the fix>
Automation:     <implemented | infeasible | deferred> - <reason>
Decision:       <replace | add | delete | cross-reference | no change>
Verification:   <checks performed, and the observed failure without the rule>
Next action:    <edit made, check added, follow-up owner, or stop>
Residual risk:  <what still depends on judgment or future enforcement>

6. See also

  • architecture-guidelines — first-principles rules that updates from this skill propagate back into.
  • defect-shift-left — when a recurring correction can be encoded as a Stage 0–5 gate instead of a SKILL rule (Directive 1).
  • gate-lifecycle — keeps a lesson's gate proven after it lands.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.