| name | skill-improvement |
| description | Use before marking any task done, to decide what durable learning to write back and which skill file owns it. |
Skill improvement
Overview
Every agent session produces two outputs:
- The work — the content change, fix, or PR.
- The learning — what the next agent needs to know.
Output 1 without output 2 leaves this repository no smarter. The learning goes
in docs/skills/, in the same commit as the work, never as a follow-up.
When to Use
Use before reporting completion, opening a PR, or handing off a session —
including sessions that succeeded on the first try.
When NOT to Use
Do not use to record session state, task progress, current status, issue
ledgers, or one-off instructions. Those live in the agent's session folder and
are never committed.
Core Process
- Preflight. Verify the repository, remote, branch, and which skills you
loaded against source before editing.
- Detect. Treat stale, contradictory, missing, or failed guidance as a
repair signal. Do not silently work around a wrong skill.
- Repair. Update the closest owning skill when the fix is source-backed
and in scope. Prefer editing an existing skill over creating a new one.
- Validate. Run the smallest relevant check from
../validation/SKILL.md, including
npm run check:docs for any documentation change.
- Write back. Commit the skill update with the work, staging explicit
paths only.
- Escalate. Stop for design changes, production claims, credentials, or
cross-repository breakage. Autonomy repairs known failures; it does not
manufacture approval.
What to write back
Write it:
| Category | Example |
|---|
| Non-obvious correctness requirement | A route loads its manifest eagerly, so a successful build does not prove it initializes. |
| Convention not visible in the code | A content surface is generated, so the generator is the edit point rather than the output file. |
| Trial-and-error discovery | A verification step that only works in a real browser at a specific viewport. |
| Project-internal fact correction | A production entry point, remote, or deployment workflow that differs from what a previous doc claimed. |
Do not write:
| Category | Example |
|---|
| One-off task note | The commit message to use for this specific change. |
| Obvious developer knowledge | How to read git status. |
| Ephemeral state | Which branch is currently in review. |
| Contradiction of another skill | If a skill is wrong, correct that skill instead of adding a competing doc. |
Any skill stating a project-internal fact must carry a ## Verification
section with the command that re-derives that fact from source.
Which file owns it
| Changed area | Update |
|---|
| Prose, locale copy, links, data values | ../content-maintenance/SKILL.md |
| Approved design, layout, or component work | ../design-gate/SKILL.md |
| Lore, quotes, attribution, provenance | ../editorial-provenance/SKILL.md |
| Checks, staging, deployment, live status | ../validation/SKILL.md |
| Session routing, remotes, handoff | ../agent-workflow/SKILL.md |
| DNS, Workers, Pages, Wrangler | ../cloudflare/SKILL.md |
| Wolves content, cards, or approved runtime work | the matching wolves-* or guardian-* skill |
| A genuinely new reusable domain | a new skill, per ../skill-authoring/SKILL.md |
| A fact affecting 2+ factory repos | this repo first, then an issue in projectbluefin/common |
Never edit ublue-os/*. Ask the human to report upstream manually.
Banned artifacts
Delete these on sight; they collect stale text instead of updating skills.
- Changelog-style agent files:
IMPROVEMENTS.md, CHANGELOG.md, CHANGES.md,
SESSION.md.
- Committed session logs:
NOTES.md, PLAN.md, TODO.md, progress files.
- Any doc instructing an agent to "append here" — route to
docs/skills/
instead.
This does not ban product documentation or release notes owned by a human.
Common Rationalizations
| Rationalization | Reality |
|---|
| "I'll write this up in a follow-up PR." | You will not, and the next agent pays for it. Same PR, or it does not exist. |
| "This was obvious once I saw it." | You found it by trial and error, which is the definition of not obvious. |
| "A new doc explains the correct behaviour." | Two docs that disagree are worse than one that is wrong. Correct the skill in place. |
Red Flags
- A session ends with a shipped change and no skill update.
- The same failure is rediscovered in a later session.
- A workaround is used without recording why it was needed.
- A learning is deferred to a follow-up PR.
- A skill is contradicted by a new doc instead of being corrected.
Verification
Before reporting completion:
git ls-files 'IMPROVEMENTS.md' 'CHANGELOG.md' 'CHANGES.md' 'SESSION.md' 'NOTES.md' 'PLAN.md' 'TODO.md'
The command must return no output.
References
