--- name: create-skill description: Create or update Vetta-compatible Agent Skills. Use when the user asks to create a skill, add a SKILL.md workflow, register a skill in skills-manifest.json, package a skill in a Vetta plugin, or add a built-in Vetta skill preset. --- # Create a Vetta Skill Create focused Agent Skills that Vetta can execute and display. Treat the Skill files and their registration metadata as one change. ## Choose the target Infer the target from the request. If it is ambiguous, ask the user to choose before writing files. | Target | Skill directory | Required registration | | --- | --- | --- | | Global Vetta product skill | `~/.vetta/skills//` | Update `~/.vetta/skills-manifest.json`. | | Project skill | `/.vetta/skills//` | No global manifest entry; project discovery is directory-based. | | Plugin skill | `/agent/skills//` | Update `plugin.json` under `agent.skillPaths`. | | Built-in Desktop skill | `/packages/skill-presets//` | Update `/packages/skill-presets/skills-manifest.json`. | Do not place a global product Skill only in `~/.vetta/agent/skills`; that directory is Agent-compatible but does not provide the Vetta product registration metadata required by the Skills UI. ## Understand the directory protection Skill and scene roots — `~/.vetta/skills`, `~/.vetta/agent/skills`, `~/.vetta/scene`, `/.vetta/skills`, and the `.agents/skills` equivalents — are read-only so that generated artifacts never land in them. Creating a new `//` directory is exempt: once this session authors that directory, every file inside it stays writable for the rest of the session. An already-installed Skill stays read-only. `write` and `edit` reject its files, and a shell command that touches them returns a warning to move the output out. To change one, edit the source it was installed from — the plugin, the repository preset, or the project directory — or ask the user to uninstall it first. Never work around the rejection with shell redirection. ## Create the Skill 1. Convert the requested name to lowercase kebab-case. It must be 1-64 characters containing only lowercase letters, digits, and hyphens. The directory name must match the frontmatter `name`. 2. Inspect nearby Skills and relevant project documentation before writing. Reuse established terminology and tool names without copying unrelated instructions. 3. Create `/SKILL.md` with YAML frontmatter containing `name` and `description`. 4. Write the body as imperative workflow instructions. State when to inspect context, when to ask a question, what files to create or edit, and how to verify completion. 5. Add `scripts/`, `references/`, or `assets/` only when genuinely required. Keep detailed reference material outside `SKILL.md` and link to it with relative paths. 6. Do not overwrite an existing Skill or unrelated configuration without reading it first. Ask before replacing intentional behavior. Inside a protected root, an existing Skill directory cannot be overwritten at all — see the directory protection above. Use this minimal structure: ```markdown --- name: example-skill description: Describe what the Skill does and the user requests that should trigger it. --- # Example Skill Concise workflow instructions. ``` ## Register a global Vetta Skill Read the full `~/.vetta/skills-manifest.json` before editing it. The file is a root-level JSON object keyed by Skill name. Preserve every existing entry and add or update only the target Skill. Use an entry shaped like this: ```json { "example-skill": { "name": "example-skill", "version": "1.0.0", "installedAt": "", "source": "custom", "enabled": true, "type": "skill", "alias": "Optional display name", "description": "Description aligned with SKILL.md frontmatter" } } ``` If the manifest does not exist, create it as `{}` before adding the entry. Keep it valid JSON and avoid replacing unrelated Skills. Use the actual current timestamp rather than a placeholder. ## Register a built-in Desktop Skill Read the full `packages/skill-presets/skills-manifest.json`. Preserve existing entries and add the new Skill with `source: "builtin"`, `enabled: true`, `type: "skill"`, a version, and display metadata. The manifest key, entry `name`, directory name, and `SKILL.md` frontmatter name must all match. The Desktop build only packages enabled directories registered in this manifest. An unregistered preset is an error. ## Update plugin configuration Only plugin-packaged Skills use `plugin.json` registration. 1. Read the full `plugin.json` before editing it. 2. Preserve every existing `agent` field and every existing `skillPaths` entry. 3. Add a plugin-relative path. Prefer a shared parent such as `"agent/skills"` when it intentionally contains all plugin Skills; otherwise add the specific Skill directory. 4. Do not add duplicate paths. Example: ```json { "agent": { "skillPaths": ["agent/skills"] } } ``` ## Quality rules - Keep the frontmatter valid YAML at the start of the file. - Make `description` specific enough for reliable triggering; include both the capability and common request language. - Keep `SKILL.md` under 500 lines. Move large examples and domain references into `references/`. - Use relative links for files inside the Skill directory. - Do not hardcode secrets, machine-specific absolute paths, or destructive commands. - Prefer the minimum files and instructions needed for the requested workflow. ## Verify 1. Confirm the final directory matches the selected target. 2. Confirm `SKILL.md` exists and its frontmatter name matches the directory. 3. Confirm the description clearly states when the Skill should run. 4. For global or built-in Skills, parse the complete `skills-manifest.json` and confirm the target entry is present without losing existing entries. 5. For plugin Skills, confirm `plugin.json` contains the correct relative `agent.skillPaths` entry and remains valid JSON. 6. Report created or modified files and any validation that was not run.