promote-lesson - SKILL.md Agent Skill

name: promote-lesson description: Promote a personal lesson from .claude/lessons/personal.md to the team-wide tasks/lessons.md, optionally rewording for team applicability. type: skill allowed-tools: Read, Write, Edit, Bash, AskUserQuestion argument-hint: [keyword to filter lessons] user-invocable: true

Promote Lesson

Overview

Personal lessons in .claude/lessons/personal.md are gitignored — they belong to the engineer, not the team. When a personal lesson matures into a rule that every contributor should follow, promote it to the committed tasks/lessons.md. This skill is the explicit, audited path for that move.

When To Use

The engineer asks to "share a personal lesson with the team"
A personal lesson has recurred 3+ times and clearly applies to others
The engineer says "promote", "share", "make this team-wide", "add this to lessons"

When NOT To Use

Lesson is genuinely personal preference (style, individual workflow)
Lesson is already in tasks/lessons.md
The personal file does not exist or is empty (nothing to promote)

Workflow

Locate the personal file. Resolve to main worktree if in a worktree. If .claude/lessons/personal.md does not exist, tell the engineer there is nothing to promote and stop.
List candidates. Read .claude/lessons/personal.md and extract every ## header with its block. If the engineer passed a keyword argument, filter blocks whose body matches the keyword (case-insensitive). Show the list, numbered, with the title and a one-line excerpt.
Ask which to promote. Use AskUserQuestion with the numbered list. Accept multiple selections.
Reword for team. For each selected lesson, rewrite first-person language (I, my) into team-applicable phrasing (engineers, the codebase, we). Show the proposed reworded text and confirm with the engineer before writing — wording matters when it lands in a committed file.
Append to team store.
- Structured (preferred when scripts/learnings.sh is present). Add a JSONL entry with --scope team --source promotion and the reworded body, then learnings.sh regen-markdown to rebuild tasks/lessons.md:
```
bash scripts/learnings.sh add --scope team --source promotion \
  --decision-origin "<inherit from the personal entry being promoted>" \
  --severity warn --phase any \
  --title "<reworded title>" --body "<reworded body>" \
  --rule "<rule>" --applies-when "<when>"
bash scripts/learnings.sh regen-markdown
```
- Markdown fallback. Append the reworded entry to tasks/lessons.md at the bottom (newest last). Keep the structure: ## [Date] — [Title], **Correction:**, **Rule:**, **Why:**, **Applies to:**. Add a **Promoted from personal:** note with the original date so provenance is auditable.
Remove from personal file. Delete the promoted entry from .claude/lessons/personal.md. Do not leave a duplicate — the team file is now authoritative for that rule.
Suggest CLAUDE.md promotion. If the lesson is foundational (architectural rule, security constraint, repeated correction), tell the engineer this might belong in CLAUDE.md or .claude/rules/ rather than tasks/lessons.md. CLAUDE.md is for permanent standards; lessons.md is for accumulated patterns.
Offer team-wide contribute-back (optional). A team-promoted lesson can also be shared across all repos via the central toolkit. After step 5, ask via AskUserQuestion whether to open a contribute-back PR to the MTK repo (moberghr/mtk-agent-toolkit). Default is no — only offer, never auto-push.

If the engineer accepts: a. Anonymize first (mandatory). Run the anonymization checklist below against the lesson text. The lesson is going to a shared repo — it must contain zero client/repo-identifying or secret material. b. Write the anonymized lesson to a single file lessons/contributed/<YYYY-MM-DD>-<slug>.md following the format documented in lessons/contributed/README.md. c. Open a PR with gh pr create targeting main, touching only that one file. The CI workflow .github/workflows/validate-lesson-pr.yml validates path/size/secret/injection constraints and labels the PR lesson-validated; a human merges it — the workflow never auto-merges. d. Do not push anything else in that PR. One lesson per PR keeps the audit trail clean.

Anonymization checklist (every item must pass before the PR is opened):
- No client, customer, or internal repo names (replace with a generic role, e.g. "a payments service")
- No internal URLs, hostnames, ticket IDs, or employee names
- No credentials, tokens, connection strings, or key material of any shape
- No file paths that reveal a private project's structure (generalize to the pattern)
- The rule still makes sense stripped of specifics — if it doesn't, it's too project-specific to contribute; keep it in tasks/lessons.md only

Rules

Never auto-promote based on heuristics. Promotion is always explicit.
Never silently rewrite — show the proposed team wording and get confirmation.
Preserve the original capture date; mark the promotion date separately.
A promoted lesson must be removed from personal.md — duplication defeats the split.
If tasks/lessons.md does not exist (new repo), create it with the standard header before appending.

Verification

Selected lessons appended to tasks/lessons.md
First-person language rewritten and confirmed by the engineer
Selected lessons removed from .claude/lessons/personal.md
Provenance note (Promoted from personal: <date>) preserved
Engineer notified if any lesson belongs in CLAUDE.md instead
Contribute-back offered (not forced); if accepted, anonymization checklist passed and a single-file PR opened under lessons/contributed/ with no auto-merge

Red Flags

Promoting without the engineer's explicit selection
Leaving the lesson in both files (creates two sources of truth)
Promoting style preferences ("I prefer 4-space indents") that should stay personal
Mass-promoting all personal lessons in one go without per-lesson confirmation