afv-library/skills/creating-sf-skill/references/progressive_disclosure.md

Progressive Disclosure — What Goes Where

SKILL.md is the workflow controller. It tells the agent what to do and when to read other files. It does not contain the detailed content itself.

Hard Rules

These are not guidelines. Always follow them.

Content type	Goes in	Example filename
Code templates	assets/	service.cls, batch.cls, rest_resource.cls
XML schemas / metadata templates	assets/	meta_template.xml, object_schema.xml
Config samples, manifests	assets/	sfdx-project.json, package.xml
API reference docs	references/	api_patterns.md, rest_endpoints.md
Detailed decision tables (> 20 rows)	references/	error_codes.md, field_mappings.md
Step-by-step sub-procedures	references/	deployment_steps.md, migration_guide.md
Edge case handling guides	references/	edge_cases.md, null_handling.md
Full input/output examples	examples/	basic_usage.md, AccountService.cls
Sample generated files	examples/	example_output.xml, sample_trigger.trigger

What Stays in SKILL.md

Only these belong in the main file:

• Frontmatter (name, description, metadata)
• Overview (1-3 sentences)
• Scope (in/out boundary)
• Required Inputs (bullet list of what to gather)
• Workflow (numbered steps with read instructions to subdirectory files)
• Rules/Constraints (short table — max 15 rows)
• Gotchas (short table — max 10 rows)
• Output Expectations (file list only, not content)
• Cross-Skill Integration (delegation table)
• Reference File Index (maps every subdirectory file to its trigger)

Target: < 300 lines for SKILL.md body.

How to Reference from SKILL.md

Every file in a subdirectory needs a specific load instruction in the workflow section.

Good — embedded in a workflow step:

1. **Read the service template** — load `assets/service.cls` before generating.
2. **Check error handling patterns** — if the class needs custom exceptions, read `references/error_handling.md`.
3. **Compare against example** — verify output matches `examples/AccountService.cls`.

Good — in the Reference File Index:

| File | When to read |
|------|-------------|
| `assets/service.cls` | Before generating any service class |
| `references/error_handling.md` | When implementing custom exception handling |
| `examples/AccountService.cls` | To verify generated output matches expected format |

Bad — vague references the agent will ignore:

See the `references/` directory for more details.
Check `assets/` for templates.

Common Mistakes

Mistake	Why it's wrong	Fix
Inlining a 50-line code template in SKILL.md	Bloats the file, wastes tokens on every invocation	Put in assets/, add a read instruction
Pasting an API spec into the workflow	Spec content is static reference, not workflow	Put in references/, read only when needed
Adding example output inline	Examples are for validation, not every-run context	Put in examples/, reference from output section
Creating subdirectory but not referencing it	Agent never reads unreferenced files	Add entry to Reference File Index
Using "see references/" without naming a file	Agent doesn't know which file to read	Always name the specific file

Token Budget

Component	Target	Maximum
SKILL.md body	< 300 lines	500 lines
Single reference file	< 200 lines	300 lines
Single asset file	No line limit	Keep focused on one template
Single example file	< 100 lines	200 lines