mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-06 15:59:59 +08:00
f5e63fd06a
* @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator * @W-22252932 [Meta Skill] Skill Creator
86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# 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:**
|
|
|
|
```markdown
|
|
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:**
|
|
|
|
```markdown
|
|
| 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:**
|
|
|
|
```markdown
|
|
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 |
|