# Skills

Skills are reusable workflow instructions that package domain knowledge for repeatable tasks. They are loaded as textual context into the agent's prompt, not as executable plugins.

## Why Use Skills

- standardize team workflows
- reduce repeated prompt boilerplate
- improve consistency and output quality

## Typical Skill Scenarios

- bug triage and incident debugging
- release checklist automation
- documentation generation
- refactor planning and verification

## Skill Format

Skills are Markdown files with optional YAML frontmatter:

```markdown
---
name: code-review
description: Standardized code review workflow
---

# Code Review

1. Check out the target branch
2. Run `npm run check` and note all failures
3. Review each file diff for:
   - logic errors
   - missing edge cases
   - security concerns
4. Verify tests pass: `npm run test`
5. Summarize findings with file paths and line references
```

## Loading Skills

Invoke a skill in interactive mode by referencing it:

```
/skill:code-review
```

Skills can be loaded from:
- built-in skill library
- `~/.config/voxcode/skills/` directory
- project-local `.voxcode/skills/` directory
- remote URLs (via `url` field in frontmatter)

## Skill Authoring Basics

1. Define a narrow objective
2. Include clear constraints
3. Require verification steps
4. Keep output contract explicit

## Good Skill Design

- **specific**: one job per skill
- **deterministic**: same input -> similar output shape
- **safe**: includes guardrails for destructive operations
- **verifiable**: asks for concrete checks and evidence

## Team Adoption Pattern

- start with 2-3 high-frequency workflows
- review outputs and iterate prompts
- store skills in version control
- add ownership and maintenance notes

For examples and related extension patterns, see [extensions.md](extensions.md).
