Skip to content

fix(han): bring skills back under Anthropic's authoring limits - #192

Merged
mxriverlynn merged 1 commit into
v5.4.0-betafrom
fix/182-skill-guidance-limits
Aug 20, 2026
Merged

fix(han): bring skills back under Anthropic's authoring limits#192
mxriverlynn merged 1 commit into
v5.4.0-betafrom
fix/182-skill-guidance-limits

Conversation

@mxriverlynn

Copy link
Copy Markdown
Collaborator

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-release was past two limits

.claude/skills/han-release/SKILL.md had 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. 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:

New file What moved
references/attribution-rules.md The closed-issue lookup, the substantive-comment test, the bot exclusions, and the $issue_list shape (Step 2.6)
references/version-plan-rules.md The baseline, bump-level, and target rules formerly numbered 3a through 3c

Reference 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.md and evidence-rule.md name 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, and han-release link directly from their SKILL.md to the files their own reference files were reaching for.
  • evidence-rule.md pointed 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-builder now carries the rules

None 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.md gains the one-level-deep requirement, an 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 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 lint and npm test both 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.

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
mxriverlynn marked this pull request as ready for review August 20, 2026 15:49
@mxriverlynn
mxriverlynn merged commit afec4a6 into v5.4.0-beta Aug 20, 2026
2 checks passed
@mxriverlynn
mxriverlynn deleted the fix/182-skill-guidance-limits branch August 20, 2026 15:49
mxriverlynn added a commit that referenced this pull request Aug 20, 2026
collecting updates for a v5.4.0 release

* #184 
* #186 
* #189
* #190
* #191
* #192 
* misc documentation updates
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.

1 participant