agentskills-specification

Agent Skills Specification

Skill by ara.so — AI Agent Skills collection.

Agent Skills is an open format for packaging instructions, scripts, and resources that AI agents can discover and use to perform better at specific tasks. Skills are folders containing a SKILL.md file with structured information that agents can load to gain expertise in specific domains or tools.

What Agent Skills Are

Agent Skills provide:

• Standardized format for agent capabilities via Markdown with YAML frontmatter
• Discoverability through triggers and structured metadata
• Portability across different AI agent platforms
• Composability allowing agents to combine multiple skills

Installation

Agent Skills are typically distributed as folders containing at minimum a SKILL.md file:

# Clone the reference implementation
git clone https://github.com/agentskills/agentskills.git

# Or see example skills
git clone https://github.com/anthropics/skills.git

Individual skills are installed by placing them in a directory that your AI agent monitors (implementation-specific).

SKILL.md Format

Every Agent Skill must have a SKILL.md file with YAML frontmatter followed by Markdown content.

Basic Structure

---
name: skill-name-in-kebab-case
description: One-line description of what this skill does
triggers:
  - natural phrase users might say
  - another trigger phrase
  - how to use this skill
---

# Skill Name

Detailed documentation in Markdown format...

Required Frontmatter Fields

---
name: database-query-optimizer
description: Optimize SQL queries for PostgreSQL and MySQL databases
triggers:
  - optimize my database query
  - improve SQL performance
  - analyze query execution plan
  - find slow queries
  - index suggestions
  - database performance tuning
---

Field Specifications:

• name: kebab-case identifier, descriptive and unique
• description: Single line, under 200 characters
• triggers: 6-8 natural language phrases that should activate this skill

Optional Frontmatter Fields

---
name: docker-deployment
description: Deploy applications using Docker and Docker Compose
version: 1.0.0
author: Your Name
requires:
  - docker >= 20.10.0
  - docker-compose >= 2.0.0
platform:
  - linux
  - macos
triggers:
  - deploy with docker
  - create docker container
  - write dockerfile
  - docker compose setup
  - containerize application
  - build docker image
---

Creating a Complete Skill

1. Start with Frontmatter

---
name: fastapi-rest-api
description: Build REST APIs with FastAPI framework including async operations, validation, and documentation
triggers:
  - create fastapi endpoint
  - build rest api with fastapi
  - fastapi async route
  - add pydantic validation
  - setup fastapi project
  - fastapi dependency injection
version: 1.0.0
requires:
  - fastapi >= 0.100.0
  - pydantic >= 2.0.0
---

2. Add Core Documentation

# FastAPI REST API

## Overview

FastAPI is a modern, fast web framework for building APIs with Python 3.7+ based on standard Python type hints.

## Installation

```bash
pip install fastapi uvicorn[standard]

Basic Usage

Simple Endpoint

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

Run the Server

uvicorn main:app --reload

### 3. Include Real Code Examples

```python
from fastapi import FastAPI, HTTPException, Depends
from pydantic import BaseModel, Field
from typing import List, Optional
import os

app = FastAPI(title="My API", version="1.0.0")

# Models with validation
class Item(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = None
    price: float = Field(..., gt=0)
    tax: Optional[float] = None

class ItemResponse(BaseModel):
    id: int
    name: str
    price: float

# Dependency injection
def get_api_key(api_key: str = Depends(lambda: os.getenv("API_KEY"))):
    if not api_key:
        raise HTTPException(status_code=401, detail="API key required")
    return api_key

# CRUD endpoints
items_db = []

@app.post("/items/", response_model=ItemResponse, status_code=201)
async def create_item(item: Item, api_key: str = Depends(get_api_key)):
    item_dict = item.dict()
    item_dict["id"] = len(items_db) + 1
    items_db.append(item_dict)
    return item_dict

@app.get("/items/", response_model=List[ItemResponse])
async def list_items(skip: int = 0, limit: int = 10):
    return items_db[skip : skip + limit]

@app.get("/items/{item_id}", response_model=ItemResponse)
async def get_item(item_id: int):
    if item_id > len(items_db) or item_id < 1:
        raise HTTPException(status_code=404, detail="Item not found")
    return items_db[item_id - 1]

4. Add Configuration Section

## Configuration

### Environment Variables

- `API_KEY`: Authentication key for protected endpoints
- `DATABASE_URL`: Connection string for database
- `LOG_LEVEL`: Logging level (DEBUG, INFO, WARNING, ERROR)

### CORS Setup

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

### 5. Include Common Patterns

```markdown
## Common Patterns

### Background Tasks

```python
from fastapi import BackgroundTasks

def write_log(message: str):
    with open("log.txt", "a") as f:
        f.write(f"{message}\n")

@app.post("/send-notification/{email}")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"Notification sent to {email}")
    return {"message": "Notification sent"}

Error Handling

from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    return JSONResponse(
        status_code=400,
        content={"message": str(exc)},
    )

### 6. Add Troubleshooting

```markdown
## Troubleshooting

### Port Already in Use
```bash
# Change the port
uvicorn main:app --port 8001

Import Errors

Ensure all dependencies are installed:

pip install -r requirements.txt

Auto-reload Not Working

Use the --reload flag and ensure you're editing the correct file:

uvicorn main:app --reload --reload-dir ./app

## Skills Directory Structure

my-skill/ ├── SKILL.md # Required: Main skill documentation ├── resources/ # Optional: Additional files │ ├── templates/ │ ├── examples/ │ └── scripts/ └── README.md # Optional: Human-readable documentation

## Python SDK Usage

If there's a Python SDK for working with Agent Skills:

```python
from agentskills import Skill, SkillRegistry

# Load a skill
skill = Skill.from_file("path/to/SKILL.md")

# Access metadata
print(skill.name)
print(skill.description)
print(skill.triggers)

# Parse content
content = skill.parse_markdown()

# Registry for managing multiple skills
registry = SkillRegistry()
registry.discover("./skills")  # Auto-discover skills in directory

# Find skills by trigger
matched_skills = registry.match_trigger("create fastapi endpoint")

# Load skill content
skill_content = registry.get_skill("fastapi-rest-api")

Best Practices

1. Descriptive Naming

Use kebab-case names that clearly identify the project or capability:

• ✅ postgresql-database-optimization
• ✅ react-component-library
• ❌ database (too generic)
• ❌ myskill (not descriptive)

2. Effective Triggers

Write triggers as natural phrases users would say:

triggers:
  - optimize postgres queries  # ✅ Specific and natural
  - improve database performance  # ✅ Common phrasing
  - db perf  # ❌ Too abbreviated
  - use this skill  # ❌ Too generic

3. Real, Working Code

Always provide complete, executable examples:

# ✅ Complete example with imports
import os
from typing import Optional

def connect_db(db_url: Optional[str] = None):
    url = db_url or os.getenv("DATABASE_URL")
    if not url:
        raise ValueError("DATABASE_URL not set")
    return connect(url)

4. Environment Variables for Secrets

Never include actual secrets:

# ✅ Use environment variables
api_key = os.getenv("OPENAI_API_KEY")

# ❌ Never hardcode
api_key = "sk-1234567890abcdef"

5. Focus on Practical Usage

Prioritize common use cases over comprehensive API documentation:

• Installation and setup
• Most frequently used features
• Common patterns and workflows
• Troubleshooting actual problems

Skill Discovery

Agents discover skills through:

1. Directory scanning: Looking for SKILL.md files
2. Trigger matching: Comparing user input to trigger phrases
3. Context relevance: Using skill metadata to determine applicability

Validation

Basic validation checklist:

• YAML frontmatter is valid
• Required fields present: name, description, triggers
• Name is in kebab-case
• 6-8 trigger phrases provided
• Code examples are in correct language
• No hardcoded secrets
• Markdown renders correctly

Resources

• Specification: https://agentskills.io/specification
• Example Skills: https://github.com/anthropics/skills
• Documentation: https://agentskills.io
• Community: https://discord.gg/MKPE9g8aUy

Common Issues

Frontmatter Not Parsing

Ensure three dashes on their own lines:

---
name: my-skill
---

Triggers Not Matching

Make triggers conversational and specific to the domain:

triggers:
  - "create a react component"  # Better than "react"
  - "setup webpack configuration"  # Better than "webpack"

Skills Not Loading

Check file structure and ensure SKILL.md is at the root of the skill directory.