projectbluefin/website/skill-improvement

Skill improvement

Overview

Every agent session produces two outputs:

1. The work — the content change, fix, or PR.
2. 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

1. Preflight. Verify the repository, remote, branch, and which skills you

loaded against source before editing.

1. Detect. Treat stale, contradictory, missing, or failed guidance as a

repair signal. Do not silently work around a wrong skill.

1. 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.

1. Validate. Run the smallest relevant check from

`../validation/SKILL.md`, including npm run check:docs for any documentation change.

1. Write back. Commit the skill update with the work, staging explicit

paths only.

1. 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:

Do not write:

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

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.
• Superpowers session records under docs/superpowers/plans/ or

docs/superpowers/specs/. Keep plans and design drafts in the agent session folder; durable rules belong in the owning skill.

• 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

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:

• [ ] Did I discover a workaround, pattern, convention, or corrected fact?
• [ ] Does a skill already own that area?
• [ ] Did I update it, or create one when none existed?
• [ ] Is the skill update staged in this same commit?
• [ ] npm run check:docs passes.
• [ ] No banned artifact was added:

git ls-files 'IMPROVEMENTS.md' 'CHANGELOG.md' 'CHANGES.md' 'SESSION.md' 'NOTES.md' 'PLAN.md' 'TODO.md'
git ls-files 'docs/superpowers/plans/**' 'docs/superpowers/specs/**'

Both commands must return no output.

References

• `../../SKILL.md` — task→skill router.
• `../skill-authoring/SKILL.md` — how to write a

new skill.

• projectbluefin/common docs/skills/factory-onboarding.md — the factory

contract this skill implements.