create-skill · diff
git:20260717.292a963 to git:20260911.0c7a9fa
7 added, 1 removed. Audit A to A.
---
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/<skill-name>/` | Update `~/.vetta/skills-manifest.json`. |
| Project skill | `<project-root>/.vetta/skills/<skill-name>/` | No global manifest entry; project discovery is directory-based. |
| Plugin skill | `<plugin-root>/agent/skills/<skill-name>/` | Update `plugin.json` under `agent.skillPaths`. |
| Built-in Desktop skill | `<vetta-mono>/packages/skill-presets/<skill-name>/` | Update `<vetta-mono>/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`, `<project-root>/.vetta/skills`, and the `.agents/skills` equivalents — are read-only so that generated artifacts never land in them. Creating a new `<root>/<skill-name>/` 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-directory>/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.
+ 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": "<current ISO-8601 timestamp>",
"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.