Agent Skills

Agent Skills provide a standardized way to package and distribute reusable agent capabilities. A skill is a folder containing prompts, scripts, references, and metadata that agents can load on-demand to gain domain-specific expertise.

Overview

Skills in fast-agent follow the SKILL.md specification:

Portable: Self-contained folders that can be shared and version controlled
Progressive: Agents read metadata first, load full content only when needed
Composable: Multiple skills can be combined in a single agent
Discoverable: Browse and install from the skills marketplace

The skills system implements the philosophy from “Don’t Build Agents, Build Skills Instead” — focusing on packaging expertise rather than intelligence.

Quick Start

Installing Skills

# Browse available skills
fast-agent go
> /skills registry

# Install a skill
> /skills add pr-writing-review

# List installed skills
> /skills

Using Skills in Code

Skills are automatically loaded from the .fast-agent/skills/ directory:

import asyncio
from fast_agent import FastAgent

fast = FastAgent("Skill Example")

@fast.agent(
    instruction="You are a helpful assistant",
    # Skills from .fast-agent/skills/ are loaded by default
)
async def main():
    async with fast.run() as agent:
        # Agent has access to all installed skills
        await agent.interactive()

if __name__ == "__main__":
    asyncio.run(main())

Disabling Skills

Disable skills for specific agents:

@fast.agent(
    name="no_skills",
    instruction="Basic agent without skills",
    skills=[],  # Explicitly disable all skills
)

Skill Structure

A skill is a directory with a SKILL.md file:

my-skill/
├── SKILL.md              # Required: Skill metadata and documentation
├── scripts/              # Optional: Executable scripts
│   └── analyze.py
├── references/           # Optional: Reference documentation
│   └── guide.md
└── templates/            # Optional: Prompt templates
    └── template.txt

SKILL.md Format

---
name: my-skill
description: Brief description of what this skill does and when to use it
---

# My Skill

Detailed documentation about the skill.

## Prerequisites

- Python 3.12+
- uv installed

## Quick Start

```bash
# Example usage
uv run scripts/analyze.py input.txt

Workflow

First step
Second step
Final step

## Real-World Example: PR Writing Review

Here's a complete skill that extracts writing improvements from GitHub PR reviews:

```markdown
---
name: pr-writing-review
description: Extract and analyze writing improvements from GitHub PR review comments. Use when asked to show review feedback, style changes, or editorial improvements from a GitHub pull request URL.
---

# PR Writing Review

Extract editorial feedback from GitHub PRs to learn from review improvements.

## Prerequisites

- **GitHub CLI**: `gh` installed
- **Authenticated session**: `gh auth status`
- **Python**: 3.12+
- **uv**: https://github.com/astral-sh/uv

## Division of Labor

| Tool              | Responsibility                                                          |
| ----------------- | ----------------------------------------------------------------------- |
| **Python script** | API calls, parsing, file tracking across renames, structured extraction |
| **LLM analysis**  | Pattern recognition, paragraph comparison, style lesson synthesis       |

## Quick Start

> **All paths are relative to the directory containing this SKILL.md file.**

```bash
# Get suggestions and feedback
uv run scripts/extract_pr_reviews.py <pr_url>

# Get full first→final comparison for deep analysis
uv run scripts/extract_pr_reviews.py <pr_url> --diff

# Cap each dump to 2k chars for LLM prompting
uv run scripts/extract_pr_reviews.py <pr_url> --diff --max-file-chars 2000

Workflow

Step 1: Extract with `--diff`

uv run scripts/extract_pr_reviews.py https://github.com/org/repo/pull/123 --diff

Outputs:

Explicit Suggestions — exact before/after from suggestion blocks
Reviewer Feedback — plain text comments
File Evolution — first draft and final version

Step 2: Analyze the Output

A. Catalog Explicit Suggestions

Create a table of mechanical fixes:

Pattern	Original	Fixed
Grammar	”Its easier"	"It’s easier”
Filler removal	”using this way"	"this way”

B. Map Feedback to Changes

For each comment:

Find section in FIRST DRAFT
Find section in FINAL VERSION
Document what changed and why

With supporting Python script in `scripts/extract_pr_reviews.py`.

## Skill Discovery

### Interactive Mode

Use slash commands in interactive mode:

```bash
fast-agent go

# List installed skills
> /skills

# Browse marketplace
> /skills registry

# Add skill by name
> /skills add skill-name

# Remove skill
> /skills remove skill-name

CLI Management

# Override skills directory
fast-agent go --skills-dir /path/to/skills

# Disable skills
fast-agent go --skills-dir /dev/null

Creating Custom Skills

Create skill directory

mkdir -p .fast-agent/skills/my-skill
cd .fast-agent/skills/my-skill

Write SKILL.md

Create the skill metadata and documentation:

---
name: my-skill
description: What this skill does and when to use it
---

# My Skill

Full documentation here.

Add resources

Create supporting directories:

mkdir scripts references templates

Test the skill

fast-agent go
> /skills
# Verify your skill appears

Skill Templates

Analysis Skill

---
name: code-analyzer
description: Analyze code quality, security, and performance issues
---

# Code Analyzer

## Quick Start

```bash
uv run scripts/analyze.py file.py

Analysis Categories

Security: SQL injection, XSS, auth issues
Performance: O(n²) algorithms, memory leaks
Style: Naming conventions, documentation

### Integration Skill

```markdown
---
name: api-integration
description: Template for integrating with external APIs
---

# API Integration

## Configuration

1. Set environment variables:
   ```bash
   export API_KEY=your_key
   export API_URL=https://api.example.com

Test connection:
```
uv run scripts/test_connection.py
```

Available Operations

GET /resource - Fetch data
POST /resource - Create data

## Agent Card Integration

Disable skills in agent cards:

```markdown
---
name: my-agent
instruction: Agent instruction here
skills: []  # Disable all skills
---

Agent documentation.

Best Practices

Keep Skills Focused

Each skill should have a single, clear purpose:

✅ Good: pr-writing-review - Extract PR feedback
❌ Bad: github-tools - Everything GitHub-related

Use Relative Paths

All paths in SKILL.md should be relative to the skill directory:

# Good
uv run scripts/analyze.py

# Bad
uv run /abs/path/to/scripts/analyze.py

Document Prerequisites

Clearly list all dependencies:

## Prerequisites

- Python 3.12+
- uv (https://github.com/astral-sh/uv)
- GitHub CLI authenticated (`gh auth status`)
- Environment variables: `GITHUB_TOKEN`

Provide Examples

Include concrete usage examples:

## Examples

```bash
# Basic usage
uv run scripts/tool.py input.txt

# With options
uv run scripts/tool.py input.txt --format json

# Multiple inputs
uv run scripts/tool.py file1.txt file2.txt

</Accordion>

<Accordion title="Version Control" icon="code-branch">
Keep skills in Git for collaboration:

```bash
cd .fast-agent/skills/my-skill
git init
git add .
git commit -m "Initial skill version"

Advanced Usage

Skill Composition

Combine multiple skills in an agent:

# Skills are loaded from .fast-agent/skills/ by default
@fast.agent(
    instruction="Expert code reviewer and writer",
    # All skills in .fast-agent/skills/ available:
    # - pr-writing-review
    # - code-analyzer
    # - style-guide
)
async def main():
    async with fast.run() as agent:
        await agent.interactive()

Skill-Specific Agents

Create agents specialized for specific skills:

@fast.agent(
    name="pr_reviewer",
    instruction="""Expert at analyzing GitHub PR reviews.
    Use the pr-writing-review skill to extract and analyze feedback.""",
    # Skill available from .fast-agent/skills/
)

Custom Skills Directory

import os

# Override skills directory
os.environ['FASTAGENT_SKILLS_DIR'] = '/custom/skills/path'

fast = FastAgent("Custom Skills")

@fast.agent()
async def main():
    # Loads skills from custom directory
    async with fast.run() as agent:
        await agent.interactive()

Skill Marketplace

The skills registry provides curated skills:

# Browse available skills
fast-agent go
> /skills registry

Available Skills:
1. pr-writing-review - Extract PR feedback
2. code-analyzer - Analyze code quality
3. api-tester - Test API endpoints

# Install by number or name
> /skills add 1
# or
> /skills add pr-writing-review

Template Variables

Skills support template variables in SKILL.md:

{{currentDate}} - Current date and time
{{env}} - Environment information

---
name: my-skill
description: Skill with context
---

# My Skill

Documentation here.

{{currentDate}}
{{env}}

These are automatically replaced when the skill is loaded.

Troubleshooting

Skill not found

Check skills directory:

ls -la .fast-agent/skills/

# Verify SKILL.md exists
cat .fast-agent/skills/my-skill/SKILL.md

Script execution fails

Ensure paths are relative and uv is installed:

# Test from skill directory
cd .fast-agent/skills/my-skill
uv run scripts/test.py

Skills not loading

Check for explicit skill disabling:

@fast.agent(
    # Remove this line to enable default skills
    skills=[],  # This disables all skills
)

Agent Cards

Package complete agent configurations

MCP Servers

Extend agent capabilities with tools

Prompts

Create reusable prompt templates

Tool Development

Build custom tools for agents

Get Started

Core Concepts

Agent Types

Workflows

Features

CLI Reference

Configuration

Examples

Overview

Quick Start

Installing Skills

Using Skills in Code

Disabling Skills

Skill Structure

SKILL.md Format

Workflow

Workflow

Step 1: Extract with `--diff`

Step 2: Analyze the Output

A. Catalog Explicit Suggestions

B. Map Feedback to Changes

CLI Management

Creating Custom Skills

Skill Templates

Analysis Skill

Analysis Categories

Available Operations

Best Practices

Advanced Usage

Skill Composition

Skill-Specific Agents

Custom Skills Directory

Skill Marketplace

Template Variables

Troubleshooting

Agent Cards

MCP Servers

Prompts

Tool Development

Get Started

Core Concepts

Agent Types

Workflows

Features

CLI Reference

Configuration

Examples

​Overview

​Quick Start

​Installing Skills

​Using Skills in Code

​Disabling Skills

​Skill Structure

​SKILL.md Format

​Workflow

​Workflow

​Step 1: Extract with --diff

​Step 2: Analyze the Output

​A. Catalog Explicit Suggestions

​B. Map Feedback to Changes

​CLI Management

​Creating Custom Skills

​Skill Templates

​Analysis Skill

​Analysis Categories

​Available Operations

​Best Practices

​Advanced Usage

​Skill Composition

​Skill-Specific Agents

​Custom Skills Directory

​Skill Marketplace

​Template Variables

​Troubleshooting

​Related Topics

Agent Cards

MCP Servers

Prompts

Tool Development

Overview

Quick Start

Installing Skills

Using Skills in Code

Disabling Skills

Skill Structure

SKILL.md Format

Workflow

Workflow

Step 1: Extract with `--diff`

Step 2: Analyze the Output

A. Catalog Explicit Suggestions

B. Map Feedback to Changes

CLI Management

Creating Custom Skills

Skill Templates

Analysis Skill

Analysis Categories

Available Operations

Best Practices

Advanced Usage

Skill Composition

Skill-Specific Agents

Custom Skills Directory

Skill Marketplace

Template Variables

Troubleshooting

Related Topics