feat: Add structural health checks to internal-skill-optimize#439
Merged
Conversation
Extends the skill beyond content trimming with two structural checks that run on ALL files including _*.md partials (unlike content optimization, which skips partials): - TOC check: flag/insert a ## Contents block on any file over 100 lines (Anthropic guidance — long files need a TOC so partial reads see full scope) - Reference-depth check: report (never auto-fix) reference chains deeper than one level from a skill (SKILL → A → B), which cause partial-read misses Content optimization is unchanged (still skips partials, still skips <80-line files). Structural checks carve out the sole partial-touching exception and the depth check is report-only (flattening moves content — out of scope). Dogfooded the skill's own TOC. SPEC mirror updated in lockstep.
There was a problem hiding this comment.
Pull request overview
Adds structural “health checks” to the /internal-skill-optimize skill (TOC insertion for long files and a reference-depth audit) and updates the corresponding SPEC mirror to reflect the new behavior and scoping rules.
Changes:
- Expanded
/internal-skill-optimizeto include two structural checks (TOC for files >100 lines; report-only reference-depth chains >1). - Clarified differing scoping rules between content trimming (skips
_*.mdand <80 lines) vs structural checks (runs on all files, including partials). - Updated
SPEC-internal-skill-optimize.mdto mirror the new flow/output fields.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| src/kit/skills/internal-skill-optimize.md | Documents new structural checks, adds a ## Contents section, and updates execution/constraints to reflect expanded behavior. |
| docs/specs/skills/SPEC-internal-skill-optimize.md | Mirrors the updated skill behavior, flow, and constraints in the SPEC. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| | Signal | What to look for | Fix | | ||
| |--------|-----------------|-----| | ||
| | **Missing table of contents** | A file **over 100 lines** with no `## Contents` (or `## Table of Contents`) block near the top. Anthropic's guidance: long files need a TOC so a partial read (`head -100`) still reveals the full scope. | Insert a `## Contents` bullet list of the file's `##`-level section headings, immediately after the H1 (and after the `_preamble.md` blockquote / frontmatter if present). List section titles only — no prose. | |
Collaborator
Author
There was a problem hiding this comment.
Fixed in 5f7c2389 — the placement guidance now states explicit document order: frontmatter → H1 → _preamble.md blockquote (if present) → ## Contents → first section.
| - If a skill is already under 80 lines, report it as "Already lean — skipped" and move on | ||
| - **Content optimization** DO NOT touch any `_*.md` partial — every `_*.md` file is a shared partial: the reference, not the target. **Structural checks are the sole exception**: a TOC insertion may add a `## Contents` block to a partial, and the depth check may *report* on a partial — neither trims a partial's prose. | ||
| - The reference-depth check is **report-only** — it never restructures or moves content (flattening a deep chain is a separate, content-moving change). | ||
| - If a skill is already under 80 lines, report it as "Already lean — skipped" for **content** optimization — but still run the **structural** checks on it (a 90-line file can still need a TOC if it crosses 100 lines later; the depth check applies regardless of length). |
Collaborator
Author
There was a problem hiding this comment.
Fixed in 5f7c2389 — rephrased to make it explicit that the TOC check is a no-op below 100 lines, while the depth check applies at any length (so a sub-80-line file is only ever flagged for a deep reference chain, never a missing TOC).
sahil-noon
marked this pull request as ready for review
June 20, 2026 12:45
Five precision/consistency fixes from Copilot review (PR #439): - Contents TOC bullets stripped to section titles only (was carrying prose, violating the skill's own 'titles only' rule) - TOC placement guidance now states explicit document order (frontmatter → H1 → preamble blockquote → Contents → first section) - Rephrased the contradictory sub-80-line parenthetical: TOC check is a no-op below 100 lines; depth check applies at any length - Aligned both SPEC 'Already lean' strings to the skill's 'Already lean — skipped'
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.
Summary
Extends
/internal-skill-optimizebeyond content trimming with two structural health checks, encoding skill-maintenance best practices into the tool itself (so they're repeatable, not one-off).New structural checks — run on all skill files including
_*.mdpartials (unlike content optimization, which skips partials):## Contentsblock on any file over 100 lines. Per Anthropic's skill-authoring guidance, long files need a table of contents so a partial read (head -100) still reveals the full scope.SKILL → A → B), which cause Claude to partial-read nested files and miss content.Unchanged: content optimization still skips
_*.mdpartials and files under 80 lines. The structural checks carve out the sole partial-touching exception (a TOC insert / depth report never trims a partial's prose), and the depth check is report-only because flattening a chain moves content — out of scope for an automatic write.Notes
## Contentsblock was added under its new rule (it's now 116 lines).docs/specs/skills/SPEC-internal-skill-optimize.mdupdated in lockstep (constitution requirement).Follow-ups (not in this PR)
/internal-skill-optimizebatch mode to apply the new checks across all skills (TOC sweep on 24 files >100 lines; content trim on the big skills likefab-operator/fab-setup; depth-chain report)._cli-fab.md(778 lines) by command-family — a separate change, since it moves content (which this skill deliberately does not do).🤖 Generated with Claude Code