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

Skill Authoring Best Practices

Principles for writing high-quality skills. Based on patterns observed across the afv-library and the Agent Skills best practices guide.

Core Principles

1. Add What the Agent Lacks, Omit What It Knows

The most common mistake is including general knowledge the LLM already has. Focus exclusively on:

• Project-specific conventions — naming patterns, directory structure, coding standards unique to this project.
• Domain-specific procedures — workflows, API quirks, deployment steps that are not publicly documented or are team-specific.
• Gotchas — failure modes, edge cases, known bugs that the agent would not anticipate.

Omit: general programming concepts, language syntax, well-known design patterns.

2. Extract from a Hands-On Task

The best skills are written after doing the task manually:

1. Perform the task yourself (or watch someone do it).
2. Note every decision point, tool invocation, and gotcha encountered.
3. Write the skill as the instructions you wish you had before starting.
4. Feed real execution traces back into the skill.

3. Refine with Real Execution

"The first draft of a skill usually needs refinement. Run the skill against real tasks, then feed the results — all of them, not just failures — back into the creation process."

After generating a skill:

• Run it against 3-5 real prompts.
• Read the full execution trace, not just the final output.
• Identify: false positives, false negatives, wasted tokens, vague instructions.

4. Task-Oriented, Not Concept-Oriented

Structure skills around what the agent should do, not what exists.

Bad: "Apex supports various class types including Service, Selector, Domain..."

Good: "1. Identify the class type needed. 2. Read the matching template from assets/. 3. Generate the class following the template pattern."

5. Concise Over Comprehensive

Every token in a SKILL.md costs compute and risks confusing the agent with irrelevant instructions. Cut ruthlessly:

• Remove sections the agent never follows.
• Remove examples that duplicate other examples.
• Remove caveats about edge cases that never happen.

Description Writing

The description is the most important field — it determines when the skill triggers.

Do

• Front-load the primary use case.
• Include specific keywords users say: "Apex", ".cls", "trigger", "batch job".
• Add TRIGGER when: and DO NOT TRIGGER when: clauses.
• Be pushy: list implicit triggers where the user may not use the domain term directly.
• Keep it factual and specific.

Don't

• Use vague language: "helps with Salesforce development".
• Include implementation details: "uses the AccountService pattern".
• Make it too narrow: only one exact phrase triggers it.
• Make it too broad: triggers on everything.

Be Pushy About Triggers

Err on the side of listing more implicit triggers, not fewer. A skill that never fires is useless; a skill that fires on a near-miss is recoverable. Explicitly call out contexts where the skill applies even if the user doesn't name the domain directly:

"TRIGGER when: user asks to add a rule, restrict a field, or enforce a policy — even if they don't explicitly say 'validation rule' or 'Apex'."

This is especially important for domain keywords the user may not know (e.g., they say "make this field required" not "add a required validation rule").

Template

<Primary purpose statement>. ALWAYS ACTIVATE when <high-confidence triggers>.
Use this skill for <broader use cases>. TRIGGER when: <specific list — include implicit
contexts where the user may not use the exact domain term>.
DO NOT TRIGGER when: <exclusions with delegation targets>.

Workflow Structure

Phase-Based

For multi-step skills, use numbered phases:

### Phase 1 — Discover
1. **Read project conventions** — check for existing patterns.
2. **Identify inputs** — what context is needed.

### Phase 2 — Generate
3. **Read template** — load the matching template.
4. **Author code** — generate following the template.

### Phase 3 — Validate
5. **Run checks** — execute validation tools.
6. **Report** — present results.

Decision Matrices

For complex decisions, use tables instead of nested conditionals:

| Scenario | Pattern | Template |
|----------|---------|----------|
| Standard async work | Queueable | assets/queueable.cls |
| Large datasets | Batch Apex | assets/batch.cls |
| Recurring schedule | Schedulable | assets/schedulable.cls |

Anti-Patterns

Anti-Pattern	Why It's Bad	Fix
Wall of text with no structure	Agent can't find relevant instructions	Use headers, tables, numbered steps
Generic advice	Wastes tokens on things the agent knows	Add only project-specific knowledge
Deeply nested conditionals	Agent loses track of which branch it's in	Flatten into decision tables
Too many optional steps	Agent follows all of them, wasting time	Make steps required or remove them
Missing gotchas section	Agent hits known pitfalls	Add gotchas from real execution failures
Referencing files that don't exist	Agent hallucinates content	Verify all referenced paths exist
Duplicating content from other skills	Wastes tokens and risks staleness	Reference the other skill instead

Cross-Skill Integration Patterns

When your skill needs another skill's capability:

1. Delegate explicitly: "For Apex tests, delegate to generating-apex-test skill."
2. Define boundaries clearly: "This skill handles X. For Y, use Z skill."
3. Don't duplicate: If another skill covers a topic, reference it, don't copy.