progressive-disclosure

Name: progressive-disclosure
Author: datarobot-oss

22stars19forks

How to install progressive-disclosure?

datarobot-oss/datarobot-agent-skills/progressive-disclosure

$npx -y skills add datarobot-oss/datarobot-agent-skills --skill progressive-disclosure

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Progressive Disclosure
2
3	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.
4
5	## Guardrails
6
7	- Do not rewrite, reinterpret, simplify, or change the meaning of skill content.
8	- Do not delete details because they seem verbose. Move details to reference files instead.
9	- Do not change SDK guidance, commands, workflows, safety notes, or examples except to preserve links after moving content.
10	- Do not edit plugin manifests, versions, `CODEOWNERS`, or unrelated repo metadata unless the user explicitly asks.
11	- Do not create deeply nested references. Reference files should be directly linked from `SKILL.md`.
12	- Do not move first-use trigger guidance, required safety constraints, or critical prerequisites out of `SKILL.md`.
13	- If content needs substantive editing, stop and ask the user before making that change.
14
15	## Target Shape
16
17	Keep `SKILL.md` focused on:
18
19	- Frontmatter with accurate `name` and `description`
20	- When to use the skill
21	- Quick start or primary workflow
22	- Key decision points and safety constraints
23	- Direct links to reference files
24
25	Move long supporting content into files such as:
26
27	- `reference.md`
28	- `examples.md`
29	- `troubleshooting.md`
30	- `platform-setup.md`
31	- `sdk-operations.md`
32	- `ci-cd-patterns.md`
33
34	Choose names that match the moved section. Prefer a small number of meaningful files over many tiny fragments.
35
36	Use folders only when the supporting material has a clear type or grouping:
37
38	- `references/` for longer conceptual guides, examples, and workflow details
39	- `scripts/` for executable helpers that the skill may ask the agent to run
40	- Language folders such as `python/`, `typescript/`, or `r/` when a skill supports multiple programming languages
41
42	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.
43
44	## Workflow
45
46	1. Inspect the target skill:
47	- Read `skills/<skill-name>/SKILL.md`.
48	- Check current line count and major headings.
49	- Check current token warning/error status from `task test:integration` when available.
50	- Identify sections that are detailed reference material, long examples, command recipes, troubleshooting tables, platform-specific variants, or API details.
51
52	2. Propose the split before editing when the change is substantial:
53	- List which sections will stay in `SKILL.md`.
54	- List which sections will move and the destination reference file for each.
55	- Keep a simple traceability map: original heading -> destination file -> replacement link text.
56	- Confirm any ambiguous sections with the user.
57
58	3. Move content with minimal transformation:
59	- Preserve headings and body text as much as possible.
60	- Adjust heading levels only when needed for valid Markdown structure.
61	- Preserve code blocks exactly unless a relative link/path must change.
62	- Keep warnings, prerequisites, and safety notes attached to the relevant content.
63
64	4. Replace moved content with concise pointers:
65
66	```markdown
67	For detailed deployment configuration, see [deployment-reference.md](deployment-reference.md).
68	```
69
70	Each pointer should explain when to read the reference, not summarize the whole reference.
71
72	5. Keep links one level deep:
73	- `SKILL.md` should link directly to every reference file the agent may need.
74	- Reference files may link back to `SKILL.md` if useful.
75	- Avoid chains like `SKILL.md` -> `references/overview.md` -> `references/deep-reference.md`.
76
77	6. Validate:
78	- Run `task test:integration` for structural checks.
79	- Run `task lint` when tooling is available.
80	- 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.
81
82	## Candidate Section Heuristics
83
84	Good move candidates:
85
86	- Long examples that are not needed for initial task routing
87	- Repeated setup variants by platform or provider
88	- Detailed SDK method inventories
89	- Troubleshooting catalogs
90	- Extended CI/CD snippets
91	- Long validation or debugging procedures
92
93	Usually keep in `SKILL.md`:
94
95	- The first-pass decision tree
96	- Required safety constraints
97	- Minimal happy-path workflow
98	- Short command checklist needed for most runs
99	- Links to all supporting references
100
101	## Diff Review Checklist
102
103	Before finishing, verify:
104
105	- Every moved block still exists in a reference file.
106	- `SKILL.md` links directly to each new reference file.
107	- The frontmatter `description` still includes clear trigger scenarios.
108	- The final re

People who liked this also viewed

6 picks

Type

progressive-disclosure

22stars19forks

View on GitHub

How to install progressive-disclosure?

datarobot-oss/datarobot-agent-skills/progressive-disclosure

$npx -y skills add datarobot-oss/datarobot-agent-skills --skill progressive-disclosure

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Progressive Disclosure
2
3	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.
4
5	## Guardrails
6
7	- Do not rewrite, reinterpret, simplify, or change the meaning of skill content.
8	- Do not delete details because they seem verbose. Move details to reference files instead.
9	- Do not change SDK guidance, commands, workflows, safety notes, or examples except to preserve links after moving content.
10	- Do not edit plugin manifests, versions, `CODEOWNERS`, or unrelated repo metadata unless the user explicitly asks.
11	- Do not create deeply nested references. Reference files should be directly linked from `SKILL.md`.
12	- Do not move first-use trigger guidance, required safety constraints, or critical prerequisites out of `SKILL.md`.
13	- If content needs substantive editing, stop and ask the user before making that change.
14
15	## Target Shape
16
17	Keep `SKILL.md` focused on:
18
19	- Frontmatter with accurate `name` and `description`
20	- When to use the skill
21	- Quick start or primary workflow
22	- Key decision points and safety constraints
23	- Direct links to reference files
24
25	Move long supporting content into files such as:
26
27	- `reference.md`
28	- `examples.md`
29	- `troubleshooting.md`
30	- `platform-setup.md`
31	- `sdk-operations.md`
32	- `ci-cd-patterns.md`
33
34	Choose names that match the moved section. Prefer a small number of meaningful files over many tiny fragments.
35
36	Use folders only when the supporting material has a clear type or grouping:
37
38	- `references/` for longer conceptual guides, examples, and workflow details
39	- `scripts/` for executable helpers that the skill may ask the agent to run
40	- Language folders such as `python/`, `typescript/`, or `r/` when a skill supports multiple programming languages
41
42	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.
43
44	## Workflow
45
46	1. Inspect the target skill:
47	- Read `skills/<skill-name>/SKILL.md`.
48	- Check current line count and major headings.
49	- Check current token warning/error status from `task test:integration` when available.
50	- Identify sections that are detailed reference material, long examples, command recipes, troubleshooting tables, platform-specific variants, or API details.
51
52	2. Propose the split before editing when the change is substantial:
53	- List which sections will stay in `SKILL.md`.
54	- List which sections will move and the destination reference file for each.
55	- Keep a simple traceability map: original heading -> destination file -> replacement link text.
56	- Confirm any ambiguous sections with the user.
57
58	3. Move content with minimal transformation:
59	- Preserve headings and body text as much as possible.
60	- Adjust heading levels only when needed for valid Markdown structure.
61	- Preserve code blocks exactly unless a relative link/path must change.
62	- Keep warnings, prerequisites, and safety notes attached to the relevant content.
63
64	4. Replace moved content with concise pointers:
65
66	```markdown
67	For detailed deployment configuration, see [deployment-reference.md](deployment-reference.md).
68	```
69
70	Each pointer should explain when to read the reference, not summarize the whole reference.
71
72	5. Keep links one level deep:
73	- `SKILL.md` should link directly to every reference file the agent may need.
74	- Reference files may link back to `SKILL.md` if useful.
75	- Avoid chains like `SKILL.md` -> `references/overview.md` -> `references/deep-reference.md`.
76
77	6. Validate:
78	- Run `task test:integration` for structural checks.
79	- Run `task lint` when tooling is available.
80	- 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.
81
82	## Candidate Section Heuristics
83
84	Good move candidates:
85
86	- Long examples that are not needed for initial task routing
87	- Repeated setup variants by platform or provider
88	- Detailed SDK method inventories
89	- Troubleshooting catalogs
90	- Extended CI/CD snippets
91	- Long validation or debugging procedures
92
93	Usually keep in `SKILL.md`:
94
95	- The first-pass decision tree
96	- Required safety constraints
97	- Minimal happy-path workflow
98	- Short command checklist needed for most runs
99	- Links to all supporting references
100
101	## Diff Review Checklist
102
103	Before finishing, verify:
104
105	- Every moved block still exists in a reference file.
106	- `SKILL.md` links directly to each new reference file.
107	- The frontmatter `description` still includes clear trigger scenarios.
108	- The final re

People who liked this also viewed

6 picks

Type