improve-skills
Skill6 starsChanged 8 days agoMITView on GitHub
Consolidates the retros of the agent flow and the objective signals (CI failures on agent branches, reverts) and proposes adjustments to the skills in a PR that a person reviews. It never edits the skills without a PR or loosens controls. Use with "/improve-skills", "what did we learn from the last runs?", "tune the skills with use" or in the scheduled weekly run.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- dvy1987/agent-loomtheir own version, first seen Nov 15, 2026
- ccomkhj/skillstheir own version, first seen Oct 24, 2026
- adhyayanrathi01/product-manager-ostheir own version, first seen Sep 6, 2026
- zrosenfield/sharepoint-ai-skillstheir own version, first seen Aug 4, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- zrosenfield/sharepoint-ai-skills★ 96same name
- ccomkhj/skills★ 10same name
- dvy1987/agent-loom★ 4same name
- adhyayanrathi01/product-manager-os★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- docs/llms.txtllms.txt
- llms.txtllms.txt
- add-memberSkill
- create-issueSkill
- db-migrationSkill
- debugSkill
- git-workflowSkill
- implement-issueSkill
- orchestrateSkill
- plan-featureSkill
- project-statusSkill
- remove-memberSkill
- review-prSkill
- update-docsSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 1 is distinctive, and 1 is very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
If there is nothing new, say so and finish.
- Very specific: line 32
Script before text: If it can be verified mechanically (a CI check, a control in verify.py or prepare.sh), do that.
“Common” is measured: kept by at least 6 in 10 of the 3 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.
Files
Improve the skills with use
Skills learn from their use, but they do not rewrite themselves: this skill proposes, a person decides. An unchecked adjustment fits a single case, makes the skills longer and, above all, tends to remove the controls that stop the agent, which are precisely the most valuable thing.
1. Gather the signals
.claude/skills/improve-skills/signals.sh [days]It brings the new retros from the agents/retros branch (since consolidated.md; one file per retro, with skill_sha to know which version of the skill it was done with, and model and role to know who did it) and those of the old agentes/retros branch (0.9), which is not rewritten: the old keys and values are shown with the new ones, so they count as the same group. It also brings the objective signals: CI failures on claude/ branches grouped by workflow, and reverts. The objective signals weigh more than the retros: the agent does not see its own blind spots.
If there is nothing new, say so and finish.
2. Group by pattern
For each pattern: what happened, in which cases (links), and which skill or script would have prevented it. A pattern is something that repeats or was serious; an anecdote is not a pattern.
Group the deviations and findings by model and by role. If the same model fails repeatedly on a type of issue (type: or area:), it is a case for the routing rule of orchestrate (which issues go to Haiku and which to Sonnet): it is proposed in the PR, without loosening the escalation of agents_map.py or the reviewer. Retros with model: unknown or role: session do not enter that comparison.
3. Decide what to propose
Rules, in this order:
- At least two cases, or one serious one. Serious: a bug that reached review or production, a broken business rule, data or money at risk.
- Never remove or loosen Autonomy rules (the "Agent autonomy" section of
AGENTS.md), approvals, verifications or the "does not merge / does not approve". If a control stops things often for no reason, it is raised as a question for the team in the PR, not as a change. - Script before text. If it can be verified mechanically (a CI check, a control in
verify.pyorprepare.sh), do that; one more instruction in Markdown is the last resort. Instructions are what the agent skips. - Maximum length: no
SKILL.mdgoes over 120 lines. If an adjustment does not fit, something else has to be removed or moved to a script. - One change per pattern, with its reason and the cases that justify it.
- Rules: what is useful but not enough to change a skill (one case, or something that cannot be verified with a script) is proposed as a
proposedrule in a PR tobarrilete-rules(ADR-006 D1), with its evidence. A person accepts it by merging;sync-rulesthen injects it into the roles. The kit keeps no lessons file, and the other agents never read raw retros.
4. Propose in a PR
Branch claude/<n>-improve-skills-<date> (with a type:task issue), based on the working trunk branch. The PR body:
## Patterns found
| Pattern | Cases | Proposed adjustment |
## Questions for the team
(controls that stop things often; none of this is changed in this PR)
## Discarded
(anecdotes or cases that do not meet the rules)Show the PR draft before opening it and wait for a "yes".
5. Mark what is consolidated
With the PR open, mark how far you consolidated with the commit that signals.sh printed ("consolidate up to"):
.claude/skills/improve-skills/retro.sh --consolidated <commit> <link to the PR>signals.sh prints one commit per branch (the new one and the 0.9 one): mark each. It writes consolidated.md on the agents/retros branch (the 0.9 branch's point goes there too: that branch is not touched); the next run starts from there. Use that commit and not the current tip: that way you do not skip retros that arrived while you were putting the PR together.
Scheduling it
To have it run on its own (for example, on Mondays), use a scheduled task that runs /improve-skills. It still ends in a PR to review: scheduling it does not give it permission to merge.
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
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.

