Skip to content

docs(skills): add lean-mcp-tools and changelog-entry - #90

Merged
lcottercertinia merged 2 commits into
mainfrom
docs/skills
Aug 4, 2026
Merged

docs(skills): add lean-mcp-tools and changelog-entry#90
lcottercertinia merged 2 commits into
mainfrom
docs/skills

Conversation

@lukecotter

Copy link
Copy Markdown
Collaborator

Two skills, written from what #87 and #86 taught, so the next change to a tool definition or a changelog entry does not have to relearn it. Contributor tooling only: no source file changes, no changelog entry, nothing shipped in the package.

  • lean-mcp-tools — where a fact belongs (a definition costs tokens on every request, instructions once per session, a response once per call), what a definition may hold, restructuring instead of deleting, the z.partialRecord win, measuring the whole wire object, and the three assertions that gate it.
  • changelog-entry — the shape of one entry, what earns one, versions and migration notes, and why a stacked-branch conflict in ## [Unreleased] keeps both sides.

Each is one SKILL.md under .claude/skills/, symlinked from ~/.claude/skills/ so it is available in every project.

Tested, not asserted

Both were written test-first, following superpowers:writing-skills. A subagent got the task with no mention of skills, twice: once before the skill existed, once after.

lean-mcp-tools — the baseline invented an annotations: { priority: 6 } hint, dropped readOnlyHint and openWorldHint, restated "in milliseconds" in three per-property descriptions, added an outputSchema, and listed six pre-ship checks, none of which measured anything. With the skill: no invented hint, no duplicated title, "in milliseconds" moved to instructions, outputSchema declined for the double-send reason, and the checks became the per-tool budget, the total against the last published figure, and the keyword assertion — plus a unit test to pin the annotations.

changelog-entry — the baseline wrote five past-tense entries for one user-visible change, promoted z.partialRecord and the spec reasoning into user-facing lines, referenced the issue on the first entry only, and used an inline URL. With the skill: one present-tense line, a reference definition under <!-- Unreleased -->, and the mechanism, the spec detail and the contributor-facing eval check all left out as unobservable to someone upgrading.

Both skills were selected from their description alone, with no prompting.

@lcottercertinia
lcottercertinia merged commit 3157900 into main Aug 4, 2026
10 checks passed
@lcottercertinia
lcottercertinia deleted the docs/skills branch August 4, 2026 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants