skill-improvement

name	skill-improvement
version	1.0
last_updated	2026-07-20
id	skill-improvement
one_line_purpose	Capture durable agent learnings in maintained skill docs.
entry_point	docs/skills/meta/skill-improvement/SKILL.md
category	meta
mcp_compliance_level	partial
status	active
dependencies	[]
tags	["skills","learning","factory"]
description	The self-improvement loop: when and how to write a skill update for a code change. Load when you changed tests, workflows, actions, or scripts.
metadata	{"type":"pattern","audience":"agents","maturity":"stable"}

Skill Improvement Mandate

Every agent session that changes this repo produces two outputs:

1. The work — the PR, fix, or test coverage improvement
2. The learning — what a future agent should know

Output 1 without Output 2 leaves the factory no smarter. The loop only compounds if agents write back.

This is the factory-wide two-output rule; the canonical statement lives in common/docs/skills/factory-onboarding.md. This file covers what is specific to testsuite.

Banned artifacts — delete on sight: changelog files (CHANGELOG.md, IMPROVEMENTS.md, SESSION.md), committed session logs and plan files (NOTES.md, PLAN.md, TODO.md, plans/*.md), and any doc instructing you to "append here". Route the content to the matching docs/skills/** file instead. plans/*.fmf are TMT/fmf test metadata, not session logs — leave them.

Before You Mark Work Complete

Run this checklist before enqueuing any PR:

• Did I discover any workaround, non-obvious pattern, or convention?
• Is there a skill file for the area I worked in?
• If yes — did I update it?
• If no — did I create one in docs/skills/?
• Is the skill file committed in this same PR? (Not a follow-up. Same PR.)

If all five are checked, you're done. If any are unchecked, finish them first.

No CI job enforces this. The skill-drift check was retired in #681; the mandate is now a review expectation. Reviewers reject PRs that change tests/**, .github/workflows/**, .github/actions/**, or scripts/** without a matching skill update.

What Counts as a Learning Worth Writing Back

Write it:

Category	Example