# 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/` 2. **Permissions**: Made executable (chmod 755 on Unix) 3. **Version tracking**: Content hash stored in `.g3/bin/.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//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//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/