# Progressive Disclosure > Refactor large DataRobot skill files by moving detailed content into directly linked reference files while preserving meaning. Use when a skill triggers context-window warnings, needs progressive disclosure, or should be chunked without changing guidance. - Skill: `datarobot-oss/progressive-disclosure` (Agent Skill) - Install (CLI): `npx skillmds@latest add datarobot-oss/progressive-disclosure` - Raw SKILL.md: https://api.skillmd.com/api/skills/datarobot-oss/progressive-disclosure/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: datarobot-oss (https://skillmd.com/u/datarobot-oss) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/datarobot-oss/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.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: ```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. 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.