| 1 | --- |
| 2 | name: build-skill |
| 3 | description: Build or improve Agent Zero skills following the official SKILL.md standard. Use when the user asks to create, rename, move, audit, test, or refactor a skill, or when a workflow should be packaged as reusable skill instructions. |
| 4 | --- |
| 5 | |
| 6 | # Build Skill |
| 7 | |
| 8 | Skills are small folders that teach Agent Zero a repeatable workflow. Keep the always-visible metadata precise, keep `SKILL.md` lean, and move detailed material into scripts, references, or assets only when the task needs it. |
| 9 | |
| 10 | ## Standard Shape |
| 11 | |
| 12 | Every skill folder must be named exactly like the skill and contain `SKILL.md`. |
| 13 | |
| 14 | ```text |
| 15 | skill-name/ |
| 16 | ├── SKILL.md |
| 17 | ├── scripts/ # optional deterministic helpers |
| 18 | ├── references/ # optional details loaded only when needed |
| 19 | └── assets/ # optional output resources or templates |
| 20 | ``` |
| 21 | |
| 22 | The frontmatter should contain `name`, `description`, and optional `triggers` when lexical discovery needs phrases that do not fit naturally in the description: |
| 23 | |
| 24 | ```yaml |
| 25 | --- |
| 26 | name: skill-name |
| 27 | description: What the skill does and when to use it. |
| 28 | triggers: |
| 29 | - "user phrase that should surface this skill" |
| 30 | --- |
| 31 | ``` |
| 32 | |
| 33 | Use lowercase letters, digits, and hyphens. Prefer short verb-led names such as `build-skill`, `review-plugin`, or `host-file-editing`. |
| 34 | |
| 35 | ## Workflow |
| 36 | |
| 37 | 1. Identify two or three real user requests that should trigger the skill. |
| 38 | 2. Decide whether the skill belongs in core `skills/` or inside a plugin's `plugins/<plugin>/skills/` directory. |
| 39 | 3. Write the frontmatter description with the core trigger condition and key context; add `triggers` for short user phrases that should rank highly in skill search or relevant-skill recall. |
| 40 | 4. Keep the body focused on procedure, contracts, failure handling, and the files/scripts to load next. |
| 41 | 5. Move long examples, schemas, policies, or variant-specific detail to one-level-deep `references/` files. |
| 42 | 6. Add scripts only for deterministic or repeatedly rewritten operations, and test representative scripts. |
| 43 | 7. Validate by searching, loading, and using the skill on a median-user prompt. |
| 44 | |
| 45 | ## Placement |
| 46 | |
| 47 | Use plugin-scoped skills when the skill exists to explain a plugin-owned tool or UI surface. Examples: Browser workflows belong under `_browser`; A0 CLI host tools belong under `_a0_connector`; Desktop canvas workflows belong under `_desktop`. |
| 48 | |
| 49 | Use root `skills/` for Agent Zero framework workflows that are not owned by one plugin, such as building skills, developing core features, or managing community plugins. |
| 50 | |
| 51 | ## Writing Rules |
| 52 | |
| 53 | - Put trigger language in frontmatter, not in a body section. Use `description` for the compact always-visible purpose and `triggers` for phrase matches used by search and relevant-skill recall. |
| 54 | - Do not add README, changelog, quick reference, or install guide files inside the skill. |
| 55 | - Avoid compatibility aliases in prompts or skill bodies when renaming; update references to the new name. |
| 56 | - Prefer concise examples over long prose. |
| 57 | - Do not duplicate the same guidance in both `SKILL.md` and references. |
| 58 | - When multiple skills could apply, keep each skill's responsibility narrow and name the handoff clearly. |
| 59 | |
| 60 | ## Validation |
| 61 | |
| 62 | Run targeted checks after edits: |
| 63 | |
| 64 | ```bash |
| 65 | conda run -n a0 pytest tests/test_skills_runtime.py tests/test_tool_action_contracts.py -q |
| 66 | ``` |
| 67 | |
| 68 | Also exercise the live path when the skill changes agent-facing tool behavior: |
| 69 | |
| 70 | ```text |
| 71 | 1. Ask a short ordinary prompt that should discover the skill. |
| 72 | 2. Confirm the agent uses skills_tool search/load when appropriate. |
| 73 | 3. Confirm it calls the intended tool only after the skill is loaded when the tool is skill-gated. |
| 74 | ``` |