docs: Update documentation for Agent Skills system

Document the new Skills system introduced in recent commits:

- docs/architecture.md: Add Skills System section with discovery
  priority, embedded skills, script extraction, and key types
- docs/skills.md: New comprehensive guide covering SKILL.md format,
  discovery priority, embedded skills, research skill usage, and
  troubleshooting
- README.md: Update Agent Skills section with correct priority order,
  add embedded skills info, research skill usage, and link to Skills
  Guide in Documentation Map
- AGENTS.md: Add skill creation to Adding Features, skill extraction
  to Dangerous Code Paths, and new Skills System Entry Points section

All documentation links validated - no broken links or orphan files.

Agent: lamport

AGENTS.md

@@ -30,6 +30,7 @@
 - **New tool**: Add definition in `tool_definitions.rs`, implement in `tools/`, add dispatch case
 - **New provider**: Implement `LLMProvider` trait in `g3-providers`
 - **New CLI mode**: Add to CLI args, implement handler in `g3-cli`
+- **New skill**: Create `skills/<name>/SKILL.md`, optionally add to `embedded.rs` for binary inclusion
 - **New config option**: Add to `g3-config` structs
 
 ## Dangerous Code Paths
@@ -43,6 +44,7 @@ These areas have subtle bugs if modified incorrectly:
 | **Tool dispatch** | Missing dispatch cases cause silent failures |
 | **Retry logic** | Aggressive retries hit rate limits harder |
 | **Parser sanitization** | Inline JSON can trigger false tool call detection |
+| **Skill extraction** | Version hash mismatch causes stale scripts; path issues on Windows |
 
 ## Do's and Don'ts
 
@@ -82,3 +84,24 @@ The `analysis/deps/` directory contains static analysis artifacts generated by t
 | `limitations.md` | What could not be observed and what may invalidate conclusions |
 
 These artifacts are useful for understanding coupling, planning refactors, and identifying architectural boundaries.
+
+## Skills System Entry Points
+
+The skills system (`crates/g3-core/src/skills/`) provides extensible agent capabilities:
+
+| File | Purpose |
+|------|--------|
+| `mod.rs` | Public API: `Skill`, `discover_skills`, `generate_skills_prompt` |
+| `parser.rs` | SKILL.md parsing with YAML frontmatter validation |
+| `discovery.rs` | Multi-location discovery with priority ordering |
+| `embedded.rs` | Compile-time skill embedding via `include_str!` |
+| `extraction.rs` | Script extraction to `.g3/bin/` with version tracking |
+| `prompt.rs` | Generates `<available_skills>` XML for system prompt |
+
+**Key invariants for skills**:
+- Skill names must be 1-64 chars, lowercase + hyphens only
+- SKILL.md must have valid YAML frontmatter with `name` and `description`
+- Embedded scripts are extracted lazily (on first use)
+- Version tracking uses content hash, not timestamps
+- Higher priority locations override lower (repo > workspace > global > embedded)
+- Script extraction is Unix-only (chmod 755); Windows support is incomplete

README.md

@@ -114,9 +114,11 @@ These commands give you fine-grained control over context management, allowing y
 g3 supports the [Agent Skills](https://agentskills.io) specification - an open format for portable skill packages that give the agent new capabilities.
 
 **Skill Locations** (in priority order, later overrides earlier):
-1. Global: `~/.g3/skills/`
+1. Embedded skills (compiled into binary)
-2. Extra paths from config
+2. Global: `~/.g3/skills/`
-3. Workspace: `.g3/skills/` (highest priority)
+3. Extra paths from config
+4. Workspace: `.g3/skills/`
+5. Repo: `skills/` (highest priority, checked into git)
 
 **SKILL.md Format**:
 ```yaml
@@ -146,6 +148,12 @@ Each skill adds ~50-100 tokens to context (name + description + path). Skills ca
 - `references/` - Additional documentation
 - `assets/` - Templates, data files
 
+**Embedded Skills**: Core skills like `research` are compiled into the binary, ensuring they work anywhere without external files. Embedded scripts are automatically extracted to `.g3/bin/` on first use.
+
+**Built-in Research Skill**: Perform asynchronous web research via `background_process("research", ".g3/bin/g3-research 'your query'")`. Results are saved to `.g3/research/<id>/report.md`.
+
+See [Skills Guide](docs/skills.md) for detailed documentation.
+
 ### Provider Flexibility
 - Support for multiple LLM providers through a unified interface
 - Hot-swappable providers without code changes
@@ -483,6 +491,7 @@ Detailed documentation is available in the `docs/` directory:
 | [Tools Reference](docs/tools.md) | Complete reference for all available tools |
 | [Providers Guide](docs/providers.md) | LLM provider setup and selection guide |
 | [Control Commands](docs/CONTROL_COMMANDS.md) | Interactive `/` commands for context management |
+| [Skills Guide](docs/skills.md) | Agent Skills system, SKILL.md format, creating skills |
 | [Code Search](docs/CODE_SEARCH.md) | Tree-sitter code search query patterns |
 
 For AI agents working with this codebase, see [AGENTS.md](AGENTS.md).

docs/architecture.md

@@ -1,7 +1,7 @@
 # g3 Architecture
 
-**Last updated**: January 2025  
+**Last updated**: February 2025  
-**Source of truth**: Crate structure in `crates/`, `Cargo.toml`, `DESIGN.md`
+**Source of truth**: Crate structure in `crates/`, `Cargo.toml`, `DESIGN.md`, `skills/`
 
 ## Purpose
 
@@ -72,6 +72,7 @@ g3/
 │   ├── g3-planner/               # Planning mode workflow
 │   └── studio/                   # Multi-agent workspace manager
 ├── agents/                       # Agent persona definitions
+├── skills/                       # Embedded skills (research, etc.)
 ├── logs/                         # Session logs (auto-created)
 └── g3-plan/                      # Planning artifacts
 ```
@@ -94,6 +95,7 @@ Key modules:
 - `retry.rs` - Retry logic with exponential backoff
 - `prompts.rs` - System prompt generation
 - `code_search/` - Tree-sitter based code search
+- `skills/` - Agent Skills discovery, parsing, and extraction
 
 **Key types**:
 - `Agent<W: UiWriter>` - Main agent struct, generic over UI output
@@ -230,6 +232,57 @@ Key modules:
 
 Studio enables isolated agent sessions by creating git worktrees, allowing multiple agents to work on the same codebase without conflicts.
 
+### Skills System (Extensible Capabilities)
+
+**Location**: `crates/g3-core/src/skills/` and `skills/`  
+**Purpose**: Portable skill packages that extend agent capabilities
+
+g3 implements the [Agent Skills](https://agentskills.io) specification, allowing skills to be discovered from multiple locations and embedded into the binary for portability.
+
+Key modules in `crates/g3-core/src/skills/`:
+- `mod.rs` - Module exports and public API
+- `parser.rs` - SKILL.md frontmatter and body parsing
+- `discovery.rs` - Multi-location skill discovery with priority ordering
+- `embedded.rs` - Skills compiled into the binary via `include_str!`
+- `extraction.rs` - Script extraction to `.g3/bin/` with version tracking
+- `prompt.rs` - Generates `<available_skills>` XML for system prompt
+
+**Discovery Priority** (lowest to highest):
+1. Embedded skills (compiled into binary)
+2. Global: `~/.g3/skills/`
+3. Extra paths from config
+4. Workspace: `.g3/skills/`
+5. Repo: `skills/` (highest priority, checked into git)
+
+**Embedded Skills**:
+
+Core skills are embedded at compile time using `include_str!`, ensuring g3 works anywhere without external files:
+
+```rust
+static EMBEDDED_SKILLS: &[EmbeddedSkill] = &[
+    EmbeddedSkill {
+        name: "research",
+        skill_md: include_str!("../../../../skills/research/SKILL.md"),
+        scripts: &[
+            ("g3-research", include_str!("../../../../skills/research/g3-research")),
+        ],
+    },
+];
+```
+
+**Script Extraction**:
+
+Embedded scripts are extracted to `.g3/bin/` on first use:
+- Version tracking via content hash in `.g3/bin/<script>.version`
+- Automatic re-extraction when embedded version changes
+- Scripts are made executable (chmod 755 on Unix)
+
+**Key types**:
+- `Skill` - Parsed skill with name, description, metadata, body, path
+- `EmbeddedSkill` - Compile-time skill with SKILL.md and scripts
+
+See [Skills Guide](skills.md) for detailed usage and authoring instructions.
+
 ## Data Flow
 
 ### Request Flow

docs/skills.md

@@ -0,0 +1,340 @@
+# Agent Skills Guide
+
+**Last updated**: February 2025  
+**Source of truth**: `crates/g3-core/src/skills/`, `skills/`
+
+## Purpose
+
+This document describes g3's Agent Skills system - a mechanism for extending agent capabilities through portable skill packages. Skills allow g3 to learn new abilities without code changes.
+
+## Overview
+
+g3 implements the [Agent Skills](https://agentskills.io) specification, an open format for portable skill packages. Each skill is a directory containing:
+
+- `SKILL.md` - Skill definition with YAML frontmatter and instructions
+- `scripts/` (optional) - Executable scripts the skill can use
+- `references/` (optional) - Additional documentation
+- `assets/` (optional) - Templates, data files, etc.
+
+At startup, g3 discovers skills from multiple locations and injects a summary into the system prompt. When the agent needs a skill, it reads the full `SKILL.md` using the `read_file` tool.
+
+## Quick Start
+
+### Using Existing Skills
+
+Skills are automatically discovered. To see available skills, check the system prompt or look in:
+
+```bash
+# Global skills (shared across all projects)
+ls ~/.g3/skills/
+
+# Workspace skills (project-specific)
+ls .g3/skills/
+
+# Repo skills (checked into git)
+ls skills/
+```
+
+### Creating a New Skill
+
+1. Create a skill directory:
+   ```bash
+   mkdir -p skills/my-skill
+   ```
+
+2. Create `SKILL.md` with frontmatter:
+   ```markdown
+   ---
+   name: my-skill
+   description: Brief description of what this skill does and when to use it.
+   license: MIT
+   compatibility: Any requirements (e.g., "Requires Python 3.8+")
+   ---
+
+   # My Skill
+
+   Detailed instructions for the agent...
+   ```
+
+3. The skill is now available to g3.
+
+## SKILL.md Format
+
+### Frontmatter (Required)
+
+The YAML frontmatter between `---` markers defines skill metadata:
+
+```yaml
+---
+name: skill-name          # Required: 1-64 chars, lowercase + hyphens only
+description: What it does # Required: 1-1024 chars, when to use this skill
+license: Apache-2.0       # Optional: SPDX license identifier
+compatibility: Requires X # Optional: Environment requirements (max 500 chars)
+metadata:                 # Optional: Arbitrary key-value pairs
+  author: your-org
+  version: "1.0"
+---
+```
+
+**Name validation rules**:
+- 1-64 characters
+- Lowercase letters, numbers, and hyphens only
+- Must start with a letter
+- No consecutive hyphens
+
+### Body (Instructions)
+
+After the frontmatter, write detailed instructions for the agent:
+
+```markdown
+# Skill Title
+
+## Quick Start
+How to use this skill in the simplest case.
+
+## Detailed Usage
+Step-by-step instructions, examples, edge cases.
+
+## Troubleshooting
+Common issues and solutions.
+```
+
+**Best practices**:
+- Keep the description concise (it's shown in the skill summary)
+- Put detailed instructions in the body (only loaded when needed)
+- Include concrete examples
+- Document error handling
+
+## Discovery Priority
+
+Skills are discovered from multiple locations. Higher priority sources override lower ones:
+
+| Priority | Location | Use Case |
+|----------|----------|----------|
+| 1 (lowest) | Embedded | Core skills compiled into binary |
+| 2 | `~/.g3/skills/` | Global user skills |
+| 3 | Config `extra_paths` | Organization-wide skills |
+| 4 | `.g3/skills/` | Workspace-local customizations |
+| 5 (highest) | `skills/` | Repo skills (checked into git) |
+
+**Override behavior**: If the same skill name exists in multiple locations, the highest priority version wins. This allows:
+- Customizing embedded skills per-project
+- Testing skill changes without modifying global installs
+- Sharing skills across an organization via config paths
+
+## Configuration
+
+Skills can be configured in `~/.config/g3/config.toml` or `./g3.toml`:
+
+```toml
+[skills]
+enabled = true                    # Default: true
+extra_paths = [                   # Additional skill directories
+  "/org/shared/skills",
+  "~/my-skills"
+]
+```
+
+To disable skills entirely:
+
+```toml
+[skills]
+enabled = false
+```
+
+## Embedded Skills
+
+Core skills are embedded into the g3 binary at compile time, ensuring they work anywhere without external files.
+
+### Currently Embedded Skills
+
+| Skill | Description |
+|-------|-------------|
+| `research` | Web-based research via scout agent with browser automation |
+
+### How Embedding Works
+
+Embedded skills use Rust's `include_str!` macro to compile SKILL.md and scripts into the binary:
+
+```rust
+static EMBEDDED_SKILLS: &[EmbeddedSkill] = &[
+    EmbeddedSkill {
+        name: "research",
+        skill_md: include_str!("../../../../skills/research/SKILL.md"),
+        scripts: &[
+            ("g3-research", include_str!("../../../../skills/research/g3-research")),
+        ],
+    },
+];
+```
+
+### Script Extraction
+
+Embedded scripts are extracted to `.g3/bin/` on first use:
+
+1. **First run**: Script is written to `.g3/bin/<script-name>`
+2. **Permissions**: Made executable (chmod 755 on Unix)
+3. **Version tracking**: Content hash stored in `.g3/bin/<script-name>.version`
+4. **Updates**: Re-extracted automatically when embedded version changes
+
+This ensures:
+- Scripts are always available, even in fresh workspaces
+- Updates propagate automatically when g3 is upgraded
+- No manual installation required
+
+## The Research Skill
+
+The embedded `research` skill enables asynchronous web research:
+
+### Usage
+
+```bash
+# Start research (always use background_process)
+background_process("research-topic", ".g3/bin/g3-research 'Your query here'")
+
+# Check status
+shell(".g3/bin/g3-research --list")
+
+# Read results when complete
+read_file(".g3/research/<research-id>/report.md")
+```
+
+### How It Works
+
+1. **Start**: `g3-research` spawns a scout agent in the background
+2. **Execute**: Scout uses browser automation to research the topic
+3. **Save**: Results written to `.g3/research/<id>/report.md`
+4. **Read**: Agent reads the report when needed
+
+### Directory Structure
+
+```
+.g3/research/
+├── research_1738700000_a1b2c3/
+│   ├── status.json      # Machine-readable status
+│   └── report.md        # The research brief
+└── research_1738700100_d4e5f6/
+    ├── status.json
+    └── report.md
+```
+
+### Status Values
+
+- `running` - Research in progress
+- `complete` - Report ready to read
+- `failed` - Error occurred (check `error` field in status.json)
+
+## Creating Skills with Scripts
+
+Skills can include executable scripts for complex operations:
+
+### Script Location
+
+Place scripts in the skill directory:
+
+```
+skills/my-skill/
+├── SKILL.md
+├── my-script.sh        # Bash script
+├── helper.py           # Python script
+└── scripts/
+    └── complex-tool    # Subdirectory also works
+```
+
+### Referencing Scripts
+
+In SKILL.md, reference scripts relative to the skill directory:
+
+```markdown
+## Usage
+
+Run the helper script:
+```bash
+shell("skills/my-skill/my-script.sh arg1 arg2")
+```
+```
+
+### Embedding Scripts
+
+To embed scripts in the binary (for core skills), add them to `embedded.rs`:
+
+```rust
+EmbeddedSkill {
+    name: "my-skill",
+    skill_md: include_str!("../../../../skills/my-skill/SKILL.md"),
+    scripts: &[
+        ("my-script", include_str!("../../../../skills/my-skill/my-script.sh")),
+    ],
+},
+```
+
+## Context Budget
+
+Each skill adds approximately 50-100 tokens to the system prompt (name + description + path). The full SKILL.md body is only loaded when the agent reads it.
+
+**Recommendations**:
+- Keep descriptions under 200 characters
+- Put detailed instructions in the body, not the description
+- Avoid creating many small skills; consolidate related functionality
+
+## Troubleshooting
+
+### Skill Not Discovered
+
+1. Check the skill directory exists and contains `SKILL.md`
+2. Verify the frontmatter is valid YAML
+3. Ensure `name` and `description` fields are present
+4. Check for syntax errors in the YAML (use a YAML validator)
+
+### Skill Overridden Unexpectedly
+
+Skills with the same name are overridden by higher-priority sources. Check:
+- `skills/` (repo) overrides everything
+- `.g3/skills/` (workspace) overrides global and embedded
+- `~/.g3/skills/` (global) overrides embedded only
+
+### Embedded Script Not Found
+
+If `.g3/bin/<script>` doesn't exist:
+1. The skill may not have been used yet (extraction is lazy)
+2. Check permissions on `.g3/bin/` directory
+3. Try deleting `.g3/bin/<script>.version` to force re-extraction
+
+### Research Skill Issues
+
+- **Takes too long**: Try a more specific query
+- **WebDriver errors**: Ensure Safari or Chrome WebDriver is configured
+- **Empty report**: Check `status.json` for error details
+
+## Adding a New Embedded Skill
+
+To add a new skill to the g3 binary:
+
+1. Create the skill in `skills/<name>/`:
+   ```
+   skills/new-skill/
+   ├── SKILL.md
+   └── optional-script.sh
+   ```
+
+2. Add to `crates/g3-core/src/skills/embedded.rs`:
+   ```rust
+   EmbeddedSkill {
+       name: "new-skill",
+       skill_md: include_str!("../../../../skills/new-skill/SKILL.md"),
+       scripts: &[
+           ("optional-script", include_str!("../../../../skills/new-skill/optional-script.sh")),
+       ],
+   },
+   ```
+
+3. Rebuild g3:
+   ```bash
+   cargo build --release
+   ```
+
+## See Also
+
+- [Agent Skills Specification](https://agentskills.io) - The open standard
+- [Architecture: Skills System](architecture.md#skills-system-extensible-capabilities) - Internal implementation
+- [README: Agent Skills](../README.md#agent-skills) - Quick overview