aradotso 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 uniquedescription: Single line, under 200 characterstriggers: 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:
- Directory scanning: Looking for
SKILL.mdfiles - Trigger matching: Comparing user input to trigger phrases
- 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.