Progressive disclosure

Progressive Disclosure

Use this repo-local meta skill to split large skills into a concise SKILL.md plus adjacent reference files. This guides content moves and reference creation; it is not a content rewrite pass.

Guardrails

• Do not rewrite, reinterpret, simplify, or change the meaning of skill content.
• Do not delete details because they seem verbose. Move details to reference files instead.
• Do not change SDK guidance, commands, workflows, safety notes, or examples except to preserve links after moving content.
• Do not edit plugin manifests, versions, CODEOWNERS, or unrelated repo metadata unless the user explicitly asks.
• Do not create deeply nested references. Reference files should be directly linked from SKILL.md.
• Do not move first-use trigger guidance, required safety constraints, or critical prerequisites out of SKILL.md.
• If content needs substantive editing, stop and ask the user before making that change.

Target Shape

Keep SKILL.md focused on:

• Frontmatter with accurate name and description
• When to use the skill
• Quick start or primary workflow
• Key decision points and safety constraints
• Direct links to reference files

Move long supporting content into files such as:

• reference.md
• examples.md
• troubleshooting.md
• platform-setup.md
• sdk-operations.md
• ci-cd-patterns.md

Choose names that match the moved section. Prefer a small number of meaningful files over many tiny fragments.

Use folders only when the supporting material has a clear type or grouping:

• references/ for longer conceptual guides, examples, and workflow details
• scripts/ for executable helpers that the skill may ask the agent to run
• Language folders such as python/, typescript/, or r/ when a skill supports multiple programming languages

Keep these folders directly under the skill directory. SKILL.md should link directly to files inside them, such as references/workflow-details.md, without requiring the agent to follow a chain of references.

Workflow

1. Inspect the target skill:

   • Read skills/<skill-name>/SKILL.md.
   • Check current line count and major headings.
   • Check current token warning/error status from task test:integration when available.
   • Identify sections that are detailed reference material, long examples, command recipes, troubleshooting tables, platform-specific variants, or API details.

2. Propose the split before editing when the change is substantial:

   • List which sections will stay in SKILL.md.
   • List which sections will move and the destination reference file for each.
   • Keep a simple traceability map: original heading -> destination file -> replacement link text.
   • Confirm any ambiguous sections with the user.

3. Move content with minimal transformation:

   • Preserve headings and body text as much as possible.
   • Adjust heading levels only when needed for valid Markdown structure.
   • Preserve code blocks exactly unless a relative link/path must change.
   • Keep warnings, prerequisites, and safety notes attached to the relevant content.

4. Replace moved content with concise pointers:

   For detailed deployment configuration, see [deployment-reference.md](deployment-reference.md).
   

   Each pointer should explain when to read the reference, not summarize the whole reference.

5. Keep links one level deep:

   • SKILL.md should link directly to every reference file the agent may need.
   • Reference files may link back to SKILL.md if useful.
   • Avoid chains like SKILL.md -> references/overview.md -> references/deep-reference.md.

6. Validate:

   • Run task test:integration for structural checks.
   • Run task lint when tooling is available.
   • If the goal is reducing context-window warnings, rerun the relevant tests and compare warning output. This repo warns at an estimated 3300 tokens and errors at 6700 tokens.

Candidate Section Heuristics

Good move candidates:

• Long examples that are not needed for initial task routing
• Repeated setup variants by platform or provider
• Detailed SDK method inventories
• Troubleshooting catalogs
• Extended CI/CD snippets
• Long validation or debugging procedures

Usually keep in SKILL.md:

• The first-pass decision tree
• Required safety constraints
• Minimal happy-path workflow
• Short command checklist needed for most runs
• Links to all supporting references

Diff Review Checklist

Before finishing, verify:

• Every moved block still exists in a reference file.
• SKILL.md links directly to each new reference file.
• The frontmatter description still includes clear trigger scenarios.
• The final response includes the traceability map for reviewer confidence.
• No instruction, recommendation, or example changed.
• No unrelated formatting churn was introduced.
• Repo validation passes or any local tooling gap is clearly reported.