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

When to Use scripts/

Agents execute scripts as black boxes — they run --help, execute, and read output. Create scripts for deterministic tasks that should not waste tokens on LLM reasoning:

• Validating generated XML against schema
• Checking naming conventions (__c suffix, API name length limits)
• Verifying cross-element dependencies (e.g., Master-Detail requires relationshipOrder)

Rules for scripts:

• One responsibility per script
• Support --help for discoverability
• No interactive prompts
• Use structured output: JSON for results, stderr for errors
• Idempotent — safe to re-run on failure/retry
• Support --dry-run for critical operations

When to Use assets/

Create template files when the skill produces metadata from a skeleton:

• XML templates with {PLACEHOLDER} syntax for variable parts
• Include XML comments explaining each section
• Templates must be syntactically valid (minus the placeholders)
• Match the actual output file extension (.xml, .json, etc.)

Example asset (assets/object-template.xml):

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>{OBJECT_LABEL}</label>
  <pluralLabel>{OBJECT_PLURAL_LABEL}</pluralLabel>
  <nameField>
    <!-- Primary name field for the object -->
    <label>{NAME_FIELD_LABEL}</label>
    <type>{NAME_FIELD_TYPE}</type>
  </nameField>
  <deploymentStatus>Deployed</deploymentStatus>
  <sharingModel>{SHARING_MODEL}</sharingModel>
</CustomObject>

Not every skill needs assets. Many metadata generation skills (like generating-custom-field and generating-flexipage) do not use assets/ at all — they embed XML examples directly in SKILL.md. Use assets when you have reusable templates with placeholder syntax; use inline examples when showing constraint-specific snippets. Only create assets/ if there is content to put in it.

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