Skip to content

SKILL.md

Latest commit

 

History

History
170 lines (118 loc) · 12.1 KB

SKILL.md

File metadata and controls

170 lines (118 loc) · 12.1 KB
Raw
name skill-optimizer
description Review and recommend optimizations for agent-facing skill documentation files (progressive disclosure compliance, minimal contract quality, cross-file references, duplication, verbosity). Use when skill docs in a repository, skill package, or provided path have been added or modified, when preparing a PR that touches skill files, or when the user asks to review, audit, optimize, or slim down skill docs for token efficiency.

Skill Optimizer

Review agent-facing skill files against progressive disclosure principles and flag verbosity. The goal is to keep agent token consumption low while ensuring every routing hub remains self-sufficient.

Treat optimization as behavior-preserving: preserve the target skill's core intent, operating model, safety constraints, executable contracts, and capability boundaries. Recommend relocating, compressing, or de-duplicating content into progressive disclosure without adding, removing, weakening, or broadening the skill's behavior.

Scope

Accepts an optional path argument (directory or glob). If no path is provided, infer the skill scope from the request and workspace: prefer an explicitly mentioned path, then the current directory if it contains SKILL.md, then common skill locations such as .claude/skills/*, .codex/skills/*, and skills/* when they contain a SKILL.md.

Within the scope directory, discover files dynamically: treat SKILL.md as entry, identify hubs as root-level .md files referenced anywhere in the entry file (routing tables, prose links, backtick mentions, or language-specific "see" references), and treat references/*.md as reference files. Root-level .md files not referenced from the entry file at all should be flagged as potentially orphaned rather than assumed to be hubs.

On a feature branch, try to diff against the base to focus on changed files. Detection order: $GITHUB_BASE_REF (CI) → git symbolic-ref refs/remotes/origin/HEAD (extract basename) → local main. If no reliable base ref is found, review all in-scope files without diffing.

File Hierarchy Mental Model

Agent skill files form a three-level progressive disclosure stack. Understanding where each piece of information belongs is the core of this review.

Entry file (SKILL.md)        — always loaded into agent context
  ├── Routing hubs            — loaded per intent (AUTH.md, WORKFLOWS.md, API.md, RULES.md)
  │     └── References        — loaded only for exact field shapes / runtime details (references/*.md)

Each level has a token budget and a content mandate:

Level Loaded when Should contain Should NOT contain
Entry Always File nav table, intent routing, core commands or APIs, minimal inline contracts Deployment guides, platform-specific instructions, response templates, detailed format examples, lengthy error-handling prose
Hub Per intent Thin router + minimal executable contract (minimum params, endpoint or action, basic error path) Full duplication of entry-file content; content that only one sub-flow needs (push to references)
Reference On demand Exact API shapes, field enums, runtime edge cases Routing logic or contracts (those belong in hubs)

The reason this matters: every token in the entry file is paid on every agent turn, whether or not that turn touches the topic. Moving 70 lines of workflow-specific setup guidance from the entry file to a dedicated hub saves those tokens on every unrelated turn.

Review Checklist

Work through these dimensions in order. For each, read the relevant files, then report findings.

1. Progressive Disclosure Compliance

Check every level for misplaced content, not just the entry file. Use the "Should NOT contain" column from the hierarchy table as the reference.

Entry file → should push down:

  • Deployment / platform guides in the entry file (should be in a hub or reference)
  • Response templates / user-facing phrasing in the entry file (should be in the relevant hub)
  • Detailed format examples or long option catalogs in the entry file (should be in a reference or rules file)
  • Hub content that duplicates entry-file sections instead of back-linking

Hubs → should push down or sideways:

  • General error-handling rules / constraints in a hub that apply across multiple flows (should be in the rules file; hub keeps only flow-specific error handling + cross-ref)
  • Operational detail only one sub-flow needs in a hub (should be in a reference; hub keeps minimal contract + routing)
  • Content that belongs in a different hub (e.g., authentication rules in a deployment hub)

References → should push up:

  • Routing logic or contracts buried in reference files (those belong in hubs)
  • Stop conditions or preconditions that an agent needs before calling any endpoint (should be in the hub's minimal contract, not hidden in a reference)

Too-thin hubs: Also check for hubs that are too thin — containing only a back-link with no local minimal contract. An agent that jumps directly into a hub (e.g., a scheduled workflow loads WORKFLOWS.md) must be able to execute the critical path without needing to also load the entry file.

2. Minimal Contract Quality

For each routing hub, verify it has a minimal executable contract — a self-contained block that tells the agent:

  1. What credentials / IDs are needed (and where to get them)
  2. Which command, action, file, or API endpoint to use
  3. What to do on success
  4. What to do on the most common failure
  5. When not to act (preconditions / stop conditions)

A hub that says only "see SKILL.md§Section for the full flow" is missing its safety net. The contract doesn't need to be exhaustive — 3-5 lines is often enough — but it must be present and executable on its own.

For the entry file, verify that inline contracts (e.g., global gates, initialization preconditions, state prerequisites) contain only the essential fields and conditions. If a contract section exceeds ~15 lines, check whether detailed formats, option lists, or failure-handling prose can be delegated to a hub or reference.

3. Cross-File Reference Integrity

Check explicit link forms first: § references, language-specific "see FILE.md" patterns, Markdown links ([text](file.md#heading)), and relative paths (./, ../). For plain-text backticked file mentions (e.g., `WORKFLOWS.md` in prose), only validate when they unambiguously resolve to an existing file — skip illustrative or code-like mentions to avoid false positives. For each validated pointer:

  • Verify the target file exists
  • For § references, verify the heading text matches any #–###### heading in the target file
  • For #anchor links, use a GitHub-compatible slugger (e.g., github-slugger or equivalent) to generate expected IDs from headings, then compare. Do not hand-roll normalization rules — edge cases around punctuation, Unicode, and duplicate-heading suffixes make manual matching unreliable.
  • Flag imprecise § references (e.g., §Persistent State Contract when the heading is §Persistent State Contract (Required))
  • Flag orphaned files: hubs or references that exist on disk but are never referenced from any routing table or cross-link

4. Duplication Detection

Look for these common duplication patterns:

Pattern Example Fix
Same flow described in 2+ files Authentication flow in both SKILL.md and AUTH.md Keep full version in one file, minimal contract + back-link in the other
Same response template in 2+ places User-facing wording in SKILL.md and WORKFLOWS.md Keep in one place only
Scattered identical reminders "Complete X before proceeding" before every section Replace with single top-level declaration
Redundant execution requirements Blockquote restating what a gate already says Replace with one-line reference to the gate
Inconsistent data shapes user[] vs user.id vs full JSON Unify to single canonical shape
Bullet-level partial duplication Hub section has 4 bullets; 3 restate general rules already in entry or rules file, only 1 is hub-specific Keep the hub-specific bullet(s), replace the rest with a single cross-reference line

Scanning granularity: Don't stop at section-level comparison. For each hub section that looks "unique as a whole," check whether its individual bullets / sub-points duplicate rules already stated in the entry file, rules file, or other hubs. A section with N bullets where N-1 are duplicates is still a duplication problem — it just hides behind a unique section heading.

5. Verbosity Analysis

Flag sections where the same information could be conveyed in fewer tokens:

  • Prose → table: Multiple deployment options described in paragraphs → comparison table
  • Repeated points: Bulleted list where 3+ bullets say the same thing in different words
  • Over-long table cells: Cells with 40+ character parenthetical annotations → simplify cell, add cross-reference
  • Redundant blockquotes: "Execution requirements" that restate what the contract/gate already says
  • Nested sub-sections for simple content: Three ### sub-sections that could be a single flat list

Output Format

## Progressive Disclosure
[list violations with file:section, or "Compliant"]

## Minimal Contracts
[list hubs missing self-sufficient contracts, or "All hubs have self-sufficient contracts"]

## Cross-File References
[list broken/imprecise refs, or "All references resolve"]

## Duplication
[list duplicated content with file:section pointers, or "No significant duplication"]

## Verbosity
[list verbose sections with compression suggestion, or "Reasonable density"]

## Suggested Changes
[prioritized list, each tagged [high] / [medium] / [low]]
- [high] file:section — what to change and why
- [medium] ...
- [low] ...

## Stats
- Entry file: X lines (target: <500)
- Hub files: Y lines total
- Reference files: Z lines total
- Estimated saveable lines: ~N

Execution Steps

  1. Determine scope from the user-provided path/glob or infer a likely skill root. Discover entry/hub/reference files dynamically.
  2. Read the entry file fully — this is the primary audit target
  3. Read each hub file
  4. For all reference files, extract the full heading list (needed for anchor validation), then skim body content for orphans, stale shapes, and verbose sections
  5. Run the 5-dimension checklist above
  6. Produce the output report — avoid restating the same finding in both a dimension section and Suggested Changes
  7. Do NOT automatically apply changes — only recommend. The user decides what to act on.

Example Findings (from real optimization)

These are patterns this review has caught in practice — use them as calibration for severity:

  • [high] 63-line persistent-state contract with format examples and option catalogs in always-loaded entry file → compress to 10-line minimal contract, move details to RULES.md
  • [high] 73-line deployment guide (3 options + provider-specific instructions) in entry file → move to DEPLOYMENT.md, replace with one-line routing reference
  • [medium] Session restore flow fully described in both SKILL.md§Session Restore and AUTH.md§Identity Restore → hub keeps 3-line local contract + back-link
  • [medium] "Complete X before proceeding" scattered 5 times before individual sections → single top-level declaration
  • [medium] Same response template in 3 places across 2 files → keep in one place only
  • [medium] Hub section with 4 error-handling bullets; 3 duplicated general rules from entry file and rules file, only 1 was hub-specific → keep hub-specific bullet, replace rest with single cross-reference
  • [medium] General credential-invalidation rules (don't reinitialize blindly, clear stale credential, retry without stale credential) in a scheduled-workflow hub → belongs in rules file; hub keeps only the workflow-specific invalid-session case + cross-ref
  • [low] Table cell with 40+ character parenthetical → simplify, add cross-ref for details
  • [low] Cross-reference using inexact heading text → use exact § heading