alex/g3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update documentation for Agent Skills system

Browse Source 
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
This commit is contained in:
Dhanji R. Prasanna
2026-02-05 14:26:26 +11:00
parent c3549ce043
commit 74c2671e1b
4 changed files with 430 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
AGENTS.md
View File

@@ -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

15
README.md
View File

@@ -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/`
2. Extra paths from config
3. Workspace: `.g3/skills/` (highest priority)
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)
**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).

57
docs/architecture.md
View File

@@ -1,7 +1,7 @@
# g3 Architecture
**Last updated**: January 2025
**Source of truth**: Crate structure in `crates/`, `Cargo.toml`, `DESIGN.md`
**Last updated**: February 2025
**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

340
docs/skills.md Normal file
View File

@@ -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