docs(skills): add lean-mcp-tools and changelog-entry - #90
Merged
Conversation
lcottercertinia
approved these changes
Aug 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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,instructionsonce per session, a response once per call), what a definition may hold, restructuring instead of deleting, thez.partialRecordwin, 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.mdunder.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 anannotations: { priority: 6 }hint, droppedreadOnlyHintandopenWorldHint, restated "in milliseconds" in three per-property descriptions, added anoutputSchema, and listed six pre-ship checks, none of which measured anything. With the skill: no invented hint, no duplicatedtitle, "in milliseconds" moved toinstructions,outputSchemadeclined 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, promotedz.partialRecordand 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.