diff --git a/docs/agents/skills.mdx b/docs/agents/skills.mdx
index 72379f6ba..20bfcd4c9 100644
--- a/docs/agents/skills.mdx
+++ b/docs/agents/skills.mdx
@@ -1,5 +1,73 @@
 ---
 title: "Skills"
-description: "Defining agent skills"
+description: "Reusable prompt templates that extend agent capabilities"
 ---
 
+Skills are reusable prompt templates that give agents structured instructions for common tasks -- code review, committing, test writing, refactoring, and more. They are discovered automatically from convention directories, listed in the agent's system prompt, and can be invoked either by the user (with `/skill-name` syntax) or by the agent itself (via the `use_skill` tool).
+
+Arc implements the open [Agent Skills](https://agentskills.io/home) format. Each skill is a directory containing a `SKILL.md` file with YAML frontmatter and Markdown instructions. See the [Agent Skills specification](https://agentskills.io/specification) for the full file format, and [What are skills?](https://agentskills.io/what-are-skills) for an introduction.
+
+## Discovery
+
+Arc discovers skills from three convention directories, searched in order:
+
+| Directory | Scope |
+|---|---|
+| `~/.arc/skills/` | Global -- applies to all projects |
+| `{git_root}/.arc/skills/` | Project -- checked into the repo |
+| `{git_root}/skills/` | Project (alternate location) |
+
+Within each directory, Arc looks for `*/SKILL.md` files (one level of nesting).
+
+When the same skill name appears in multiple directories, **later directories override earlier ones**. This means project-level skills take precedence over global skills, letting you customize behavior per-repo.
+
+<Note>
+You can override the default directories by setting `skill_dirs` in the session configuration. When set, only the specified directories are searched.
+</Note>
+
+## Invocation
+
+Skills can be invoked in two ways.
+
+### Slash syntax (user input)
+
+Users can reference a skill with a `/` prefix in their input:
+
+```
+/commit fix the off-by-one error in pagination
+```
+
+Arc detects the `/commit` token, finds the matching skill, and expands the input by replacing the skill reference with the full template. The remaining text (`fix the off-by-one error in pagination`) is substituted into the `{{user_input}}` placeholder.
+
+Rules for slash syntax:
+- The `/` must be preceded by whitespace or be at the start of the input
+- The skill name must be followed by whitespace or end of input
+- Only one skill reference per input is allowed
+- File paths like `/usr/bin/bash` are not matched (the character after `/` must be a lowercase letter, and the name cannot contain `/`)
+
+### use_skill tool (agent-initiated)
+
+When skills are available, Arc adds a `use_skill` tool to the agent's toolset and lists the available skills in the system prompt:
+
+```
+# Available Skills
+When the user's request matches a skill below, call the `use_skill` tool
+to load its instructions, then follow them.
+- `commit`: Create a git commit following best practices
+- `review`: Review code changes for issues and improvements
+```
+
+The agent can call `use_skill` with a skill name to load the template, then follow the instructions:
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `skill_name` | string | yes | Name of the skill to load (without the `/` prefix) |
+
+Returns the skill's template text.
+
+## Lifecycle
+
+1. **Discovery** -- On session startup, Arc scans the skill directories and parses all valid `SKILL.md` files
+2. **Registration** -- If any skills are found, the `use_skill` tool is registered and the skill list is added to the system prompt
+3. **Expansion** -- When user input contains a `/skill-name` reference, Arc expands it before sending to the LLM
+4. **Tool use** -- The agent can also call `use_skill` at any time to load a skill's template mid-conversation