afv-library/skills/creating-sf-skill/SKILL.md

name	description	license	metadata
creating-sf-skill	AI-assisted skill authoring pipeline for the afv-library. Use when the user wants to create a new skill, update an existing skill, generate a skill spec, scaffold skill files, or add a new capability to the skill catalog. TRIGGER when: user says create skill, new skill, skill creator, author skill, scaffold skill, generate skill, update skill, add a skill, skill pipeline. DO NOT TRIGGER when: user is directly editing an existing SKILL.md without asking for guided authoring.Invoke this skill whenever someone needs to add a new capability to the afv-library skill catalog, or wants to update/improve an existing skill. This includes creating skills for Apex, metadata, LWC, Flow, Agentforce, or any Salesforce domain.	LICENSE.txt has complete terms	version stage 1.0 Pilot

Instructions

You are a contributor onboarding tool for the afv-library. Your job is to take minimal input and generate a complete, validated skill as fast as possible. Ask one thing at a time. Generate first, refine after. Do not explain the pipeline.

The full contribution lifecycle has 5 phases:

Phase	What	Status
1	Gather authoritative input	This skill handles
2	Generate v1 Draft	This skill handles
3	Generate test stubs	This skill handles
4	Run eval, move to Under Review	Next step for contributor
5	Push PR to afv-library, CI publishes	Final step for contributor

---

On Start

If the user passed $ARGUMENTS (a skill name), check if skills/$0/SKILL.md already exists. If yes, use AskUserQuestion: options Update existing skill | Create new skill with different name.

Otherwise proceed to Step 1.

---

Step 1 — Infer or confirm skill type

Try to infer the skill type from the user's message before asking.

If the user mentions…	Infer type
metadata, object, field, validation rule, permission set, flow, layout, component, prompt template	Metadata generation
Apex class, trigger, batch, LWC, JavaScript, test class	Code generation
deploy, debug, setup, migrate, process, pipeline	Workflow / process

• If confident: state the inferred type inline. Suggest 2-3 gerund skill names, pick one as your recommendation, and briefly explain why (e.g. most specific, matches naming convention, clearest intent). Move to Step 2.
• If genuinely uncertain: use AskUserQuestion:

question: "What kind of skill do you want to create?"
header: "Skill type"
options:
  - label: "Metadata generation"
    description: "Creates Salesforce metadata — custom objects, fields, validation rules, etc."
  - label: "Code generation"
    description: "Generates Apex classes, triggers, LWC components, or other code artifacts."
  - label: "Workflow / process"
    description: "Guides the user through a multi-step process — deployments, debugging, org setup, etc."
  - label: "Other"
    description: "Something else — I'll describe it."

After confirming type, suggest 2-3 skill names inline using the gerund naming convention (e.g., generating-validation-rule, building-data-cloud-connector). Present as text, not a question.

---

Step 2 — Describe the skill + gather reference material

Do not expose step numbers to the user. Never say "Step 2" or label sections in user-facing messages.

Use AskUserQuestion to understand the use case:

header: "Use case"
question: "What's the use case for this skill? Tell me what problem it solves, who would use it, and what it should produce.

If you have any examples, schemas, or docs handy, feel free to share them too — a file path, URL, or paste works."
options:
  - label: "I'll describe it here"
    description: "Type your use case and I'll generate from that."
  - label: "I have reference material"
    description: "I'll share a schema, example file, or doc."

Read every resource the user provides. Then summarize what you extracted — keep it tight, 2-3 bullets max:

Extracted context: • … • …

Now generate the description using both the user's description and the extracted context. Expand it to include trigger phrases, TRIGGER when / DO NOT TRIGGER when clauses, and the word "use".

Print the description as plain text in your response message first, then call AskUserQuestion. The user cannot see the description inside the tool's question or option fields — it must appear in the message body before the tool call.

Example message format:

Here's the skill description I've drafted:

> **Skill name:** `generating-<name>`
>
> **Description:** <full description text here>

Does this capture it?

Then use AskUserQuestion:

question: "Does this description capture what you want the skill to do?"
header: "Description"
options:
  - label: "Looks good (Recommended)"
    description: "Use this and proceed to generation."
  - label: "I want to edit it"
    description: "Tell me what to change."

If they edit, incorporate and re-confirm.

Silent background work before generating:

• Scan skills/ for existing skills with overlapping scope (duplicate check).
• Identify dependency candidates from existing skill names.
• Infer gotchas from domain knowledge and the provided reference material.

---

Step 3 — Generate

Tell the user: "Generating Skill..."

Then do the work. Do not ask any more questions.

1. Read ./references/progressive_disclosure.md — use it to decide what goes in SKILL.md vs assets/ vs references/ vs examples/.
2. Read ./templates/skill_template.md.
3. Read ./templates/frontmatter_reference.yaml.
4. Read ./references/best_practices.md.
5. Generate all files following the rules below.

What goes WHERE — hard rules

SKILL.md is only for the workflow, rules, and gotchas. Everything else goes into subdirectories.

Content type	Where it goes
Code templates (.cls, .xml, .js, .html)	assets/
Code examples / sample output	examples/
API specs, schemas, XML definitions	references/ or assets/
Detailed reference tables (> 20 rows)	references/
Step-by-step guides for sub-procedures	references/
Input/output example pairs	examples/
Configuration files, manifests	assets/

What stays in SKILL.md: frontmatter, overview (1-3 sentences), scope, required inputs, workflow steps, constraint table, gotchas table (short), output expectations (file list only), cross-skill integration table, and Reference File Index.

How to reference files from SKILL.md

Every file in assets/, references/, or examples/ must have a specific load instruction in SKILL.md. Use this pattern:

1. **Read the service template** — load `assets/service.cls` before generating.
2. **For REST endpoints**, read `references/rest_api_patterns.md` for status codes.
3. **See example output** in `examples/basic_service.cls` for the expected structure.

Never write "see references/ for details." Always name the specific file and scenario.

Directory structure to create

skills/<skill-name>/
├── SKILL.md                  # Workflow + rules + gotchas ONLY (target < 300 lines)
├── assets/                   # Code templates, XML schemas, config files
├── references/               # Prose docs, detailed tables, sub-guides
├── examples/                 # Input/output pairs, sample generated files
└── tests/
    └── evals/
        ├── <skill-name>-<scenario-1>/
        │   ├── prompt.md     # Exact trigger prompt (no heading — just the prompt text)
        │   └── gold/         # Expected output artifact
        ├── <skill-name>-<scenario-2>/
        │   ├── prompt.md
        │   └── gold/
        └── <skill-name>-<scenario-3>/
            ├── prompt.md
            └── gold/

Read ./templates/tests_structure.md before scaffolding tests/.

Create assets/, references/, and examples/ only if there is content to put in them. Do NOT create tests/unit/ — only create tests/evals/ with 2-3 datasets.

Generating SKILL.md content

Frontmatter — always set stage: Draft:

---
name: <skill-name>
description: "<from Step 2>"
license: LICENSE.txt has complete terms
metadata:
  version: "1.0"
  stage: Draft
---

Body rules:

• Add what the agent lacks, omit what it knows.
• Task-oriented: every section = an instruction, not a description.
• Target < 300 lines for SKILL.md body.

Required sections:

Section	What to write
Title + overview	1-3 sentences — what and why
Scope	In-scope / out-of-scope boundary
Required Inputs	What context to gather before acting
Workflow	Numbered steps with read instructions
Rules	Hard constraints table
Gotchas	Short table of pitfalls — max 10 rows
Output Expectations	List of files produced (not their content)
Cross-Skill Integration	When to delegate (if applicable)
Reference File Index	Maps every subdirectory file to when it's read

Write all files

1. Write skills/<skill-name>/SKILL.md.
2. Write each assets/ file — code templates, schemas.
3. Write each references/ file — detailed guides, tables.
4. Write each examples/ file — sample inputs/outputs.
5. Write tests/evals/ datasets — see Step 4 below for eval content rules.

Validate

Run the validator:

npx tsx scripts/validate-skills.ts 2>&1

For the full list of rules, see ./references/validation_rules.md.

If validation fails: fix the issues and re-run. Only surface to the user if you cannot resolve an issue yourself.

---

Step 4 — Review

Tell the user:

"Your skill is generated and in draft state — please review and let me know if you'd like any changes."

Then print the file tree and key decisions:

skills/<name>/
├── SKILL.md
├── assets/<files>
├── references/<files>
├── examples/<files>
└── tests/
    └── evals/<dataset-1>/, <dataset-2>/, <dataset-3>/

Key decisions:
• <e.g. "Formula reference table moved to references/ — 25 rows, too large for SKILL.md">
• <e.g. "assets/template.xml built from the schema provided in context">
• <e.g. "5 gotchas inferred from domain knowledge">

Use AskUserQuestion:

question: "Would you like to make any changes?"
header: "Review"
options:
  - label: "Looks good"
    description: "Proceed to generating eval datasets."
  - label: "I want changes"
    description: "Tell me what to modify and I'll update the skill."

If changes requested: collect feedback, edit files, re-validate, re-print, return here.

---

Step 5 — Generate eval datasets

Read ./templates/tests_structure.md before writing eval files.

For each of 2-3 positive trigger scenarios (derived from the skill description):

tests/evals/<skill-name>-<scenario>/prompt.md — write the exact prompt a user would type. No heading, no title, no markdown framing — just the raw prompt text:

<The exact user message that should trigger this skill>

tests/evals/<skill-name>-<scenario>/gold/<artifact> — expected output file with the correct extension for the artifact type (e.g. ContactEmail.validationRule-meta.xml, AccountService.cls). Infer extension from skill type. Mark with a stub comment at the top:

# STUB — review and update expected output before running eval

Do not create seed-data/ folders — those are filled in by the contributor during eval.

Use AskUserQuestion:

question: "Eval stubs generated. How do they look?"
header: "Evals"
options:
  - label: "Looks good"
    description: "Proceed to next steps."
  - label: "Add or change some"
    description: "Tell me what to adjust."

---

Step 6 — Done

Print the final summary:

Skill: <name>
Location: skills/<name>/
Stage: Draft

What this skill does:
• <1-line summary of primary capability>
• <key scope boundary or constraint>
• <notable pattern, delegation, or integration>

Next steps:
1. Run the eval prompts in tests/evals/ and review the outputs against gold/.
   When the outputs look right, update the frontmatter: stage: Under Review
2. Once you're happy with the skill, open a PR to forcedotcom/afv-library.
   CI will validate the skill and publish it to the catalog.

---

Gotchas (for you, the agent)

Issue	What to do
Description missing "use"	Validator requires it. Always include "Use when..." in generated descriptions.
YAML parse error	Descriptions contain : — always wrap in double quotes.
Gerund naming	First word must end in -ing. Suggest names that follow this.
Body over 500 lines	Split into references/. See ./references/progressive_disclosure.md.
User gives vague input	Don't ask repeatedly — make your best guess, generate, and confirm.
Validation fails	Fix it yourself. Only ask the user if you genuinely can't resolve it.
No reference material provided	Generate representative stubs; mark everything # STUB.
Skill type is clear from user message	Do not ask — infer it, state it, move on.