Repository navigation
Gate Skill Descriptions at the 1024-Character Limit and Trim Every One Over It - #3839
Merged
Merged
Conversation
…e Over It A loader can truncate a description past the Agent Skills limit, and the tail it drops is where a description says which sibling skill wins. So build_dist.py now measures each SKILL.md's parsed frontmatter description and refuses one over DESCRIPTION_LIMIT, exit 2 under --check and exit 1 on a regenerate. PyYAML is imported lazily so skills_install.py keeps importing build_dist under a plain python3. Every over-limit description is trimmed, keeping what the skill governs, its use-whenever triggers, and its sibling-precedence clauses. Narrative the body did not already hold moves into the body. skill-lifecycle step 2 states the cap. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Owner
Author
|
A recorded local strict-review pass covers head |
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
 |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
An active nit remains in SKILL.md because its wording is ungrammatical and does not clearly express the intended unconditional scope.
1 open issue
What changed in this PR
This PR enforces the 1024-character Agent Skills description limit, trims overlong descriptions, and synchronizes the canonical skills with generated distributions and digests.
Changes:
- Adds lazy PyYAML frontmatter parsing and validation to
build_dist.py. - Adds tests for length limits, malformed frontmatter, exit codes, and lazy imports.
- Trims affected skill descriptions and regenerates GitHub, Claude, and digest outputs.
- Remaining review items: update the host menu wrappers for the new exit-2 contract, document all malformed-frontmatter failures, and correct one grammatical phrase.
This pull request requires changes.
| File | Summary |
|---|---|
tests/test_build_dist.py |
Adds frontmatter parsing, limit, malformed-input, exit-code, and lazy-import tests. |
scripts/README.md |
Documents PyYAML and description-gate behavior; host menu exit-2 handling remains to be updated. |
scripts/build_dist.py |
Implements parsed frontmatter validation and the 1024-character description gate; CLI documentation should include malformed-frontmatter failures. |
.github/skills/workflow-ci-contract/SKILL.md |
Regenerated workflow contract skill description. |
.github/skills/upstream-contribution-workflow/SKILL.md |
Regenerated upstream contribution skill description; one grammatical wording nit remains. |
.github/skills/skill-lifecycle/SKILL.md |
Documents the description limit and gate behavior. |
.github/skills/shell-codestyle/SKILL.md |
Regenerated shell codestyle skill description. |
.github/skills/session-handoff/SKILL.md |
Regenerated handoff skill description. |
.github/skills/repo-worktree/SKILL.md |
Regenerated worktree skill description. |
.github/skills/python-codestyle/SKILL.md |
Regenerated Python codestyle skill description. |
.github/skills/pr-review-conduct/SKILL.md |
Regenerated review-conduct skill description. |
.github/skills/merge-and-release/SKILL.md |
Regenerated release skill description. |
.github/skills/local-strict-review/SKILL.md |
Regenerated local-review skill description. |
.github/skills/git-commit-conventions/SKILL.md |
Regenerated commit-conventions skill description. |
.github/skills/drive-pr/SKILL.md |
Regenerated PR-driving skill description. |
.github/skills/dotnet-codestyle/SKILL.md |
Regenerated .NET codestyle skill description. |
.github/skills/decision-triage/SKILL.md |
Regenerated decision-triage skill description. |
.github/skills/copilot-instructions-keeper/SKILL.md |
Regenerated Copilot-instructions skill description. |
.github/skills/comment-and-doc-style/SKILL.md |
Regenerated documentation-style skill description. |
.github/skills/check-this-repo/SKILL.md |
Regenerated repository-check skill description. |
.github/skills/carried-instruction-file-guard/SKILL.md |
Regenerated carried-file guard skill description. |
.github/skills/branching-and-release-model/SKILL.md |
Regenerated branching skill description. |
.github/skills/backlog-burndown/SKILL.md |
Regenerated backlog skill description. |
.github/skills/audit-a-repo/SKILL.md |
Regenerated repository-audit skill description. |
.github/skills/agent-conduct/SKILL.md |
Regenerated agent-conduct skill description. |
.claude-plugin/fleet-skills/skills/workflow-ci-contract/SKILL.md |
Regenerated Claude workflow contract skill. |
.claude-plugin/fleet-skills/skills/upstream-contribution-workflow/SKILL.md |
Regenerated Claude upstream contribution skill. |
.claude-plugin/fleet-skills/skills/skill-lifecycle/SKILL.md |
Regenerated Claude skill-lifecycle skill. |
.claude-plugin/fleet-skills/skills/shell-codestyle/SKILL.md |
Regenerated Claude shell codestyle skill. |
.claude-plugin/fleet-skills/skills/session-handoff/SKILL.md |
Regenerated Claude session-handoff skill. |
.claude-plugin/fleet-skills/skills/repo-worktree/SKILL.md |
Regenerated Claude repo-worktree skill. |
.claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md |
Regenerated Claude Python codestyle skill. |
.claude-plugin/fleet-skills/skills/pr-review-conduct/SKILL.md |
Regenerated Claude review-conduct skill. |
.claude-plugin/fleet-skills/skills/merge-and-release/SKILL.md |
Regenerated Claude release skill. |
.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md |
Regenerated Claude local-review skill. |
.claude-plugin/fleet-skills/skills/git-commit-conventions/SKILL.md |
Regenerated Claude commit-conventions skill. |
.claude-plugin/fleet-skills/skills/drive-pr/SKILL.md |
Regenerated Claude PR-driving skill. |
.claude-plugin/fleet-skills/skills/dotnet-codestyle/SKILL.md |
Regenerated Claude .NET codestyle skill. |
.claude-plugin/fleet-skills/skills/decision-triage/SKILL.md |
Regenerated Claude decision-triage skill. |
.claude-plugin/fleet-skills/skills/copilot-instructions-keeper/SKILL.md |
Regenerated Claude Copilot-instructions skill. |
.claude-plugin/fleet-skills/skills/comment-and-doc-style/SKILL.md |
Regenerated Claude documentation-style skill. |
.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md |
Regenerated Claude repository-check skill. |
.claude-plugin/fleet-skills/skills/carried-instruction-file-guard/SKILL.md |
Regenerated Claude carried-file guard skill. |
.claude-plugin/fleet-skills/skills/branching-and-release-model/SKILL.md |
Regenerated Claude branching skill. |
.claude-plugin/fleet-skills/skills/backlog-burndown/SKILL.md |
Regenerated Claude backlog skill. |
.claude-plugin/fleet-skills/skills/audit-a-repo/SKILL.md |
Regenerated Claude repository-audit skill. |
.claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md |
Regenerated Claude agent-conduct skill. |
.claude-plugin/fleet-skills/.source-digests/workflow-ci-contract |
Updates the workflow contract source digest. |
.claude-plugin/fleet-skills/.source-digests/upstream-contribution-workflow |
Updates the upstream contribution source digest. |
.claude-plugin/fleet-skills/.source-digests/skill-lifecycle |
Updates the skill-lifecycle source digest. |
.claude-plugin/fleet-skills/.source-digests/shell-codestyle |
Updates the shell codestyle source digest. |
.claude-plugin/fleet-skills/.source-digests/session-handoff |
Updates the session-handoff source digest. |
.claude-plugin/fleet-skills/.source-digests/repo-worktree |
Updates the repo-worktree source digest. |
.claude-plugin/fleet-skills/.source-digests/python-codestyle |
Updates the Python codestyle source digest. |
.claude-plugin/fleet-skills/.source-digests/pr-review-conduct |
Updates the review-conduct source digest. |
.claude-plugin/fleet-skills/.source-digests/merge-and-release |
Updates the release source digest. |
.claude-plugin/fleet-skills/.source-digests/local-strict-review |
Updates the local-review source digest. |
.claude-plugin/fleet-skills/.source-digests/git-commit-conventions |
Updates the commit-conventions source digest. |
.claude-plugin/fleet-skills/.source-digests/drive-pr |
Updates the PR-driving source digest. |
.claude-plugin/fleet-skills/.source-digests/dotnet-codestyle |
Updates the .NET codestyle source digest. |
.claude-plugin/fleet-skills/.source-digests/decision-triage |
Updates the decision-triage source digest. |
.claude-plugin/fleet-skills/.source-digests/copilot-instructions-keeper |
Updates the Copilot-instructions source digest. |
.claude-plugin/fleet-skills/.source-digests/comment-and-doc-style |
Updates the documentation-style source digest. |
.claude-plugin/fleet-skills/.source-digests/check-this-repo |
Updates the repository-check source digest. |
.claude-plugin/fleet-skills/.source-digests/carried-instruction-file-guard |
Updates the carried-file guard source digest. |
.claude-plugin/fleet-skills/.source-digests/branching-and-release-model |
Updates the branching source digest. |
.claude-plugin/fleet-skills/.source-digests/backlog-burndown |
Updates the backlog source digest. |
.claude-plugin/fleet-skills/.source-digests/audit-a-repo |
Updates the repository-audit source digest. |
.claude-plugin/fleet-skills/.source-digests/agent-conduct |
Updates the agent-conduct source digest. |
.agents/skills/workflow-ci-contract/SKILL.md |
Trims the canonical workflow contract description. |
.agents/skills/upstream-contribution-workflow/SKILL.md |
Trims the canonical upstream contribution description. |
.agents/skills/skill-lifecycle/SKILL.md |
Documents the canonical description limit and gate behavior. |
.agents/skills/shell-codestyle/SKILL.md |
Trims the canonical shell codestyle description. |
.agents/skills/session-handoff/SKILL.md |
Trims the canonical handoff description. |
.agents/skills/repo-worktree/SKILL.md |
Trims the canonical worktree description. |
.agents/skills/python-codestyle/SKILL.md |
Trims the canonical Python codestyle description. |
.agents/skills/pr-review-conduct/SKILL.md |
Trims the canonical review-conduct description. |
.agents/skills/merge-and-release/SKILL.md |
Trims the canonical release description. |
.agents/skills/local-strict-review/SKILL.md |
Trims the canonical local-review description. |
.agents/skills/git-commit-conventions/SKILL.md |
Trims the canonical commit-conventions description. |
.agents/skills/drive-pr/SKILL.md |
Trims the canonical PR-driving description. |
.agents/skills/dotnet-codestyle/SKILL.md |
Trims the canonical .NET codestyle description. |
.agents/skills/decision-triage/SKILL.md |
Trims the canonical decision-triage description. |
.agents/skills/copilot-instructions-keeper/SKILL.md |
Trims the canonical Copilot-instructions description. |
.agents/skills/comment-and-doc-style/SKILL.md |
Trims the canonical documentation-style description. |
.agents/skills/check-this-repo/SKILL.md |
Trims the canonical repository-check description. |
.agents/skills/carried-instruction-file-guard/SKILL.md |
Trims the canonical carried-file guard description. |
.agents/skills/branching-and-release-model/SKILL.md |
Trims the canonical branching description. |
.agents/skills/backlog-burndown/SKILL.md |
Trims the canonical backlog description. |
.agents/skills/audit-a-repo/SKILL.md |
Trims the canonical repository-audit description. |
.agents/skills/agent-conduct/SKILL.md |
Trims the canonical agent-conduct description. |
Review effort: Lite
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…iptions Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #3839 +/- ##
===========================================
+ Coverage 81.60% 83.04% +1.43%
===========================================
Files 26 29 +3
Lines 9070 9777 +707
===========================================
+ Hits 7402 8119 +717
+ Misses 1668 1658 -10
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Owner
Author
|
A recorded local strict-review pass covers head |
This was referenced Nov 2, 2026
ptr727
added a commit
that referenced
this pull request
Nov 3, 2026
## Summary Fixes a finding Copilot raised on promotion PR #3843, against the description length gate #3839 added. `skill_description` in `scripts/build_dist.py` returned None ("states no description") for any frontmatter that was not a mapping. A `SKILL.md` whose frontmatter parsed to a list or a scalar was therefore never measured, and it got past the 1024-character gate. `skill-lifecycle` and `scripts/README.md` both say the gate refuses "frontmatter too malformed to measure one". The code now does the same: frontmatter that is not a mapping raises `frontmatter is not a mapping`, as unclosed and invalid frontmatter already did. Empty frontmatter still reads as stating no description. - `scripts/build_dist.py`: refuse non-mapping frontmatter, and keep returning None for empty frontmatter. - `tests/test_build_dist.py`: a refusal case for list frontmatter, and a not-measured case for empty frontmatter. ## Verification - `python -m unittest discover -s tests -p test_build_dist.py`: 99 tests OK. - `ruff check` and `ruff format --check` on both files: clean. - `scripts/build_dist.py --check`: generated distributions are current. - Every `SKILL.md` under `.agents/skills/` opens with mapping frontmatter, so no existing skill newly fails the build. - local-strict-review: two passes recorded at the `frontier` tier. The first raised one finding (no test covered the empty-frontmatter branch), fixed in ce00bf3. The second raised none. The receipt covers the pushed head. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Nov 3, 2026
…rge on a Running Hosted Review, and Gate Skill Description Length (#3843) Promotes the changes merged into `develop` since promotion #3797 to `main`, the end of an away-mode backlog burndown. - [#3803](#3803) exempts the Roslyn embedded-language marker (`// lang=json`, `language=`) from the prose gate's comment rules as a tool directive. - [#3807](#3807) has `local_review.py record` take `--report`, the file the reviewer wrote, bind the pass to its sha256, and derive the finding count from it. `status` gains `reportPath`. - [#3809](#3809) holds `pr_review.py merge` while a hosted review is still running on the head, and routes a declined Qodo finding to a dismiss request. - [#3811](#3811) dates an anchored `intentRef` by the section its anchor names, and lets a `driftNote` acknowledge a verified intent advisory. - [#3816](#3816) moves the null GraphQL node check into the shared `gh_graphql` transport as `NullNodeError`. - [#3818](#3818) explains the workspace-edit default in `GOVERNANCE.md` and names the aggregator's expression form. - [#3822](#3822) moves the abandon discard to the `backlog-burndown` orchestrator, aligns the abandoned-branch delete, and holds a grown agent-safety set. - [#3823](#3823) scopes the Husky prose gate to staged paths and adds `--skip-generated` so a named file inside a generated tree is skipped. - [#3828](#3828) reads Copilot's `Open findings:` label, drops the duplicate `null_node`, and matches `scripts/README.md` to the Merge Gate. - [#3829](#3829) bumps the two stale hub caller snippet pins and documents the fallback's mixed-pair refusal. - [#3831](#3831) keeps an inherited `GIT_DIR` from rerooting the prose gate's subdirectory git reads. - [#3832](#3832) gives `backlog-burndown` a disposition for a worker's standalone clone and keeps the agent-safety hold past a park. - [#3835](#3835) makes `carry.py check-sections` refuse what `apply-sections` would, and name an open fence. - [#3836](#3836) pins the reusable-workflow stubs by placeholder and ticks the PlexCleaner gates item. - [#3838](#3838) has the `runtime-secrets` audit dimension detect a bare `secrets/` directory from the tracked files that name it. - [#3839](#3839) gates skill descriptions at the 1024-character limit and trims every one over it. - [#3846](#3846) fixes an adjacent doc, an in-file pre-existing defect, and an edge case on new code in the open pull request instead of filing an issue for each, and keeps filing for code that runs elsewhere. - [#3847](#3847) refuses skill frontmatter that parses to a list or a scalar, so the description length gate cannot be bypassed. Fixes #3770 Fixes #3699 Fixes #3705 Fixes #3789 Fixes #1819 Fixes #727 Fixes #3710 Fixes #3706 Fixes #3623 Fixes #3687 Fixes #3617 Fixes #3757 Fixes #3790 Fixes #3786 Fixes #3785 Fixes #3772 Fixes #1657 Fixes #3443 Fixes #3824 Fixes #3817 Fixes #3805 Fixes #1666 Fixes #3700 Fixes #3821 Fixes #3771 Fixes #3794 Fixes #3825 Fixes #3690 Fixes #1472 Fixes #3813 Fixes #3719 Fixes #1592 Fixes #3845 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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 on promotion: #1592
Summary
The
description:frontmatter field is what makes a skill fire. Most fleet skill descriptions ran past the 1024-character Agent Skills limit, and nothing bounded them. A loader can truncate a description past that point. The part it drops is the tail, which is where these descriptions say which sibling skill wins a shared trigger.scripts/build_dist.pyparses each.agents/skills/<name>/SKILL.mdfrontmatter with PyYAML. It refuses adescriptionlonger thanDESCRIPTION_LIMIT(1024):--checkskills_install.pystill importsbuild_distunder a plainpython3git-commit-conventionsat 1014. Each trim keeps what the skill governs, its "use this whenever" triggers, and its sibling-precedence and co-fire clauses.session-handoff"Why This Exists".build_dist.py--checkexit-2 list.Verification
uv run --no-project --script scripts/build_dist.py --checkexits 0. Before the trims it exited 2 and listed every over-limit skill.DescriptionCasetests intests/test_build_dist.py:skills_installdoes not importyamlpython -m unittest discover -s tests: 3355 tests OK, 7 skipped.local-strict-review: three recorded passes.backlog-burndown.upstream-contribution-workflow) is fixed in a3b6163. Running the fix through its ownlocal-strict-reviewswept every trimmed description for the same kind of slip. It found four more and then one: a pronoun with no clear target, a possessive, a dropped "explicitly", and two narrowings of the history-rewrite clause. The final pass at 2c9d839 is clean.🤖 Generated with Claude Code