# Skill System

A skill is a loadable markdown instruction pack that switches the agent into a specific execution mode (e.g., commit message generation, code review, README generation).

## Skill format

A skill is a markdown file with YAML frontmatter for metadata:

```markdown
***
name: code-reviewer
description: Deep code review covering quality, security, and architecture
version: 1.0.0
***

You are now a strict code reviewer...
```

The frontmatter `name` is the trigger keyword. The body arrives as a `run_skill` tool result when the skill activates; since v1.1.0 it is no longer appended to the system prompt.

## Skill locations

The scanner walks ten directories (`~/.copilot/skills` and `~/.agents/skills` added in v1.2.0), so skills written for other agents load without conversion:

| Path | Source label |
|---|---|
| `<cwd>/.skills` | `local` |
| `<cwd>/.claude/skills` | `claude` |
| `~/.config/agenvoy/skills/.system` | `system` (bundled, refreshed by `make build` from `extensions/skills/`) |
| `~/.config/agenvoy/skills/.system_design` | `system` (optional skills installed with `/skill` → `system`, since v1.0.17) |
| `~/.config/agenvoy/skills` | `user` (`agenvoy` before v1.0.22) |
| `~/.claude/skills` | `claude` |
| `~/.codex/skills` | `codex` |
| `~/.opencode/skills` | `opencode` |
| `~/.copilot/skills` | `copilot` |
| `~/.agents/skills` | `agents` |

`~/.openai/skills` and its `openai` source label were removed in v1.2.1; put those skills under `~/.agents/skills` or another scanned directory.

Each skill is a directory containing `SKILL.md` plus optional scripts and templates. The source label shows next to the skill in the TUI slash picker, so it is obvious whether `/code-reviewer` came from this project, from Agenvoy's own storage, or from another agent's config.

Since v1.2.0 the skill list is no longer in the system prompt: it arrives in a per-turn context message placed before each user input (descriptions clipped to 256 characters), and the system prompt's `## Skills` block keeps only the fixed activation rules. `run_skill` loads a body on demand.

The external sources `claude`, `codex`, `copilot`, `opencode` and `agents` can be switched off since v1.2.0: `/skill` → `source` in the TUI (a multi-select; unchecked sources are skipped), the dashboard's Skills page, or `POST /v1/config/skill_source`. The list is saved as `skill_source_disabled` in `config.json` and those directories are skipped when scanning; turning off `claude` also skips `<cwd>/.claude/skills`.

## Bundled and installable skills

The bundled set is `extension-install`, `extension-upload`, `scheduler-skill-creator` and `skill-creator`. v1.0.17 removed `code-reviewer`, `commit-generate`, `readme-generate`, `version-generate` and `search-suitable-public-api` from the bundle. All of them except `search-suitable-public-api`, plus `wiki-generate` and (since v1.0.21) `go-test-generate` and `seo-optimize`, can be installed from the TUI with `/skill` → `system` (`/skills` before v1.0.22): a multi-select list where a checked entry is shallow-cloned from `github.com/agenvoy/skill-<name>` into `~/.config/agenvoy/skills/.system_design/` and an unchecked one that is present is deleted. The scanner rescans afterwards. Like `.system`, these directories cannot be deleted through `DELETE /v1/skill`.

## Always-allow list

A skill can be marked always-allow so its tool calls skip the confirm gate: `/skill` → `permission` in the TUI, global scope only (it replaced `/allow-skill` in v1.0.22; the `/dangerous` command was removed earlier), or `POST /v1/allowlist` with a `{skill: {name, scope, work_dir}}` block (`scope=global|project`). Global entries live in `~/.config/agenvoy/allow_skill`, project entries in `<project>/.agenvoy/allow_skill`, and the two are unioned at load time. An always-allow skill runs with the `auto` rules, so it only skips prompts while the working directory is a subdirectory of `$HOME` (not `$HOME` itself, not a denied or sensitive path); writes outside the working directory, irreversible commands and password prompts still ask.