agentskills-specification

# Agent Skills Specification > Skill by [ara.so](https://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: ```bash # 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 ```markdown --- 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 ```yaml --- 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 ```yaml --- 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 ```yaml --- 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 ```markdown # 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 ```python 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 ```bash 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 ```markdown ## 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 ```python 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: ```bash pip install -r requirements.txt ``` ### Auto-reload Not Working Use the `--reload` flag and ensure you're editing the correct file: ```bash 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: ```yaml 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: ```python # ✅ 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: ```python # ✅ 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: ```markdown --- name: my-skill --- ``` ### Triggers Not Matching Make triggers conversational and specific to the domain: ```yaml 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.