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

1. Propose the split before editing when the change is substantial:
2. List which sections will stay in SKILL.md.
3. List which sections will move and the destination reference file for each.
4. Keep a simple traceability map: original heading -> destination file -> replacement link text.
5. Confirm any ambiguous sections with the user.

1. Move content with minimal transformation:
2. Preserve headings and body text as much as possible.
3. Adjust heading levels only when needed for valid Markdown structure.
4. Preserve code blocks exactly unless a relative link/path must change.
5. Keep warnings, prerequisites, and safety notes attached to the relevant content.

1. Replace moved content with concise pointers:

``markdown 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.

1. Keep links one level deep:
2. SKILL.md should link directly to every reference file the agent may need.
3. Reference files may link back to SKILL.md if useful.
4. Avoid chains like SKILL.md -> references/overview.md -> references/deep-reference.md.

1. Validate:
2. Run task test:integration for structural checks.
3. Run task lint when tooling is available.
4. 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.