build-skill

# Build Skill 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. ## Standard Shape Every skill folder must be named exactly like the skill and contain `SKILL.md`. ```text skill-name/ ├── SKILL.md ├── scripts/ # optional deterministic helpers ├── references/ # optional details loaded only when needed └── assets/ # optional output resources or templates ``` The frontmatter should contain `name`, `description`, and optional `triggers` when lexical discovery needs phrases that do not fit naturally in the description: ```yaml --- name: skill-name description: What the skill does and when to use it. triggers: - "user phrase that should surface this skill" --- ``` Use lowercase letters, digits, and hyphens. Prefer short verb-led names such as `build-skill`, `review-plugin`, or `host-file-editing`. ## Workflow 1. Identify two or three real user requests that should trigger the skill. 2. Decide whether the skill belongs in core `skills/` or inside a plugin's `plugins/<plugin>/skills/` directory. 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. 4. Keep the body focused on procedure, contracts, failure handling, and the files/scripts to load next. 5. Move long examples, schemas, policies, or variant-specific detail to one-level-deep `references/` files. 6. Add scripts only for deterministic or repeatedly rewritten operations, and test representative scripts. 7. Validate by searching, loading, and using the skill on a median-user prompt. ## Placement 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`. 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. ## Writing Rules - 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. - Do not add README, changelog, quick reference, or install guide files inside the skill. - Avoid compatibility aliases in prompts or skill bodies when renaming; update references to the new name. - Prefer concise examples over long prose. - Do not duplicate the same guidance in both `SKILL.md` and references. - When multiple skills could apply, keep each skill's responsibility narrow and name the handoff clearly. ## Validation Run targeted checks after edits: ```bash conda run -n a0 pytest tests/test_skills_runtime.py tests/test_tool_action_contracts.py -q ``` Also exercise the live path when the skill changes agent-facing tool behavior: ```text 1. Ask a short ordinary prompt that should discover the skill. 2. Confirm the agent uses skills_tool search/load when appropriate. 3. Confirm it calls the intended tool only after the skill is loaded when the tool is skill-gated. ```