From 4aaa9607cca447316149141e680cb1e4098468e1 Mon Sep 17 00:00:00 2001 From: "ysachdeva@salesforce.com" Date: Tue, 5 May 2026 13:14:59 +0530 Subject: [PATCH] feat: add Scope, Required Inputs, Rules/Constraints, Output Expectations Add missing standard sections to creating-sf-skill SKILL.md so it follows its own best practices guidelines. --- skills/creating-sf-skill/SKILL.md | 52 +++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/skills/creating-sf-skill/SKILL.md b/skills/creating-sf-skill/SKILL.md index 7748f58..135275c 100644 --- a/skills/creating-sf-skill/SKILL.md +++ b/skills/creating-sf-skill/SKILL.md @@ -14,6 +14,28 @@ You are a contributor onboarding tool for the [afv-library](https://github.com/f 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. +## Scope + +- **In scope**: Gathering user intent, generating SKILL.md + supporting files (assets/, references/, examples/), scaffolding eval datasets, running validation, and iterating on feedback. +- **Out of scope**: Running evals against generated skills (contributor does this), pushing PRs (contributor does this), editing existing SKILL.md files without guided authoring. + +--- + +## Required Inputs + +Gather from the user before generating: + +- **Skill type**: Metadata generation, code generation, or workflow/process (infer from context when possible) +- **Use case description**: What problem the skill solves, who uses it, what it produces +- **Reference material** (optional): Schemas, example files, docs, URLs — anything that provides domain context + +Defaults unless specified: +- Stage: `Draft` +- Naming: gerund convention (`generating-`, `building-`, `deploying-`) +- Structure: SKILL.md < 300 lines, heavy content in subdirectories + +--- + The full contribution lifecycle has 5 phases: | Phase | What | Status | @@ -355,6 +377,36 @@ Next steps: --- +## Rules / Constraints + +| Constraint | Rationale | +|-----------|-----------| +| SKILL.md must be under 500 lines | Avoids context window bloat; forces progressive disclosure | +| Description must be 100-300 words with TRIGGER/SKIP | It is the sole activation mechanism; vague descriptions never fire | +| Description must be wrapped in double quotes | Colons and special chars break YAML parsing without quotes | +| `allowed-tools` must scope Bash to specific commands | Blanket Bash pre-approves all executions — security risk | +| Every subdirectory file must have a load instruction in SKILL.md | Agents never read unreferenced files | +| Never hardcode filesystem paths to other skills | Skill catalog layout varies across installations | +| Never hardcode `force-app/main/default/` | Customers customize `sfdx-project.json` package paths | +| Gerund naming for skill directories | Convention: first word ends in `-ing` | +| `name` field must match directory name exactly | Validator enforces this; mismatch fails CI | + +--- + +## Output Expectations + +Deliverables for every generated skill: + +- `skills//SKILL.md` — workflow + rules + gotchas (target < 300 lines) +- `skills//assets/` — code templates, XML schemas (only if needed) +- `skills//references/` — detailed guides, tables, sub-procedures (only if needed) +- `skills//examples/` — input/output pairs, sample files (only if needed) +- `skills//tests/evals/` — 2-3 eval datasets with `prompt.md` + `gold/` + +Do NOT create empty directories. Only create `assets/`, `references/`, `examples/` if there is content to put in them. + +--- + ## Gotchas (for you, the agent) | Issue | What to do |