fix(han): bring skills back under Anthropic's authoring limits - #192
Merged
Conversation
Closes #182. `.claude/skills/han-release/SKILL.md` carried a 1435-character `description` against the documented 1024-character maximum, and a 563-line body against the 500-line guideline. The description is now 791 characters, with the parent-and-child versioning explanation and the already-bumped-version behavior moved into the body where there is no budget pressure. Two blocks of domain knowledge moved out of the body into `references/attribution-rules.md` (the closed-issue attribution rules) and `references/version-plan-rules.md` (the baseline, bump-level, and target rules formerly numbered 3a through 3c), leaving the body at 480 lines. Seventy-four reference files over 100 lines now open with a `## Contents` list of their sections, so a partial read still shows the file's full scope. The sixteen output templates are left alone: a contents list on a skeleton copied whole would land in every document it produces. Twenty-three of the twenty-five reference links that sat two hops from a SKILL.md are gone. `yagni-rule.md` and `evidence-rule.md` name each other in prose instead of linking, so neither is reachable only through the other; `code-review`, `plan-implementation`, and `han-release` now link directly from SKILL.md to the files their own reference files were reaching for. `evidence-rule.md` also pointed at `../../docs/evidence.md`, which resolves in this repository and breaks for anyone who installs the plugin, so it now links the public URL. The two remaining pairs run through `docs/semantic-versioning.md`, a repository document rather than a skill reference file, and reach authoring guidance no release run needs. `han-plugin-builder` gains the rules behind all of this. `skill-reference-files.md` documents the one-level-deep requirement, the in-plugin path requirement, and the over-100-lines contents list with its template exception. `progressive-disclosure.md` and `cowork-specific-skill-instructions.md` point at those rules rather than owning a partial copy, and `skill-builder`'s review step checks them.
mxriverlynn
marked this pull request as ready for review
August 20, 2026 15:49
This was referenced Aug 20, 2026
Merged
mxriverlynn
added a commit
that referenced
this pull request
Aug 20, 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.
Closes #182.
@kasparovabi opened the issue with measured counts against Anthropic's skill authoring guidance. I re-measured on this branch, confirmed each item against the source guidance, and fixed all three.
han-releasewas past two limits.claude/skills/han-release/SKILL.mdhad a 1435-characterdescriptionagainst the documented 1024-character maximum, and a 563-line body against the 500-line guideline.The description is now 791 characters. What came out was the parent-and-child versioning explanation and the already-bumped-version behavior, both of which are process detail the body already carries.
Two blocks of domain knowledge moved out of the body into new reference files, leaving it at 480 lines:
references/attribution-rules.md$issue_listshape (Step 2.6)references/version-plan-rules.mdReference files over 100 lines now open with a contents list
The guidance asks for a table of contents past roughly 100 lines, so a partial read still shows the file's full scope. Seventy-four files now have one, listing the headings that name each file's real sections.
The sixteen output templates are left alone, as the issue suggested. A contents list on a skeleton copied whole would land in every document it produces. The new guidance states that exception rather than leaving it as an unexplained gap.
Two-hop reference links: 25 down to 2
I measured 25 pairs on this branch, not the 15 counted against
main. The fix keeps the cross-references and removes the chains:yagni-rule.mdandevidence-rule.mdname each other in prose instead of linking, so neither is reachable only through the other. The vendored copies across four plugins stay byte-identical.code-review,plan-implementation, andhan-releaselink directly from their SKILL.md to the files their own reference files were reaching for.evidence-rule.mdpointed at../../docs/evidence.md, which resolves in this repository and breaks for anyone who installs the plugin. It now links the public URL.Two pairs remain, both running through
docs/semantic-versioning.md. That is a repository document rather than a skill reference file, and it reaches authoring guidance no release run needs.han-plugin-buildernow carries the rulesNone of the three rules were in the repo's own authoring guidance, which is why the drift went unnoticed. The description-length doc already covered 1024 thoroughly; the other two were missing or misfiled.
skill-reference-files.mdgains the one-level-deep requirement, an in-plugin path requirement, and the over-100-lines contents list with its template exception.progressive-disclosure.mdandcowork-specific-skill-instructions.mdpoint at those rules instead of owning a partial copy. The one-level-deep rule had been living inside the cowork doc as though it were cowork-specific; it is general.skill-builder's review step checks all three on every new skill.Verification
npm run lintandnpm testboth pass (80 Bats tests, including the byte-identical check on the vendored rule copies). Re-measured after the changes: no description over 1024, no body over 500, no non-template reference file over 100 lines without a contents list.