How to Create Your First Agent Skill - Complete Tutorial 2026

What is an Agent Skill?

An Agent Skill is a packaged capability that extends what AI agents can do. Think of them as plugins or extensions for AI assistants like Claude, ChatGPT, or custom agents.

Skills can:

Execute code (run Python scripts, bash commands)
Access APIs (fetch weather, send emails, query databases)
Process files (read CSV, generate PDFs, manipulate images)
Automate workflows (combine multiple actions into one command)

Prerequisites

Before you start building, make sure you have:

Basic Python or TypeScript knowledge - Most skills are written in these languages
Code editor - VS Code recommended
Git installed - For version control
API keys (optional) - If your skill needs external services

Step 1: Choose Your Skill Type

Decide what problem your skill will solve:

Data Processing - Parse CSV, convert formats, extract text
API Integration - Connect to external services (Stripe, Twilio, Airtable)
Automation - Schedule tasks, monitor systems, send notifications
Analysis - Generate reports, calculate metrics, visualize data

Step 2: Set Up Your Project Structure

my-agent-skill/
|- skill.json          # Metadata and configuration
|- main.py             # Entry point
|- requirements.txt    # Dependencies
|- README.md           # Documentation
|- tests/              # Unit tests

Create skill.json

{
  "name": "my-first-skill",
  "version": "1.0.0",
  "description": "My first agent skill that does X",
  "author": "Your Name",
  "entry": "main.py",
  "dependencies": ["requests==2.31.0"]
}

Step 3: Write the Core Logic

Create main.py with a simple function:

import os
import requests

def fetch_weather(city: str) -> dict:
    """Fetch current weather for a city."""
    api_key = os.environ.get('WEATHER_API_KEY')
    if not api_key:
        return {"error": "API key not configured"}

    url = f"https://api.weather.com/v1/current?city={city}"
    response = requests.get(url, headers={"Authorization": f"Bearer {api_key}"})

    if response.status_code == 200:
        return response.json()
    return {"error": "Failed to fetch weather"}

if __name__ == "__main__":
    result = fetch_weather("New York")
    print(result)

Step 4: Add Security Best Practices

Never hardcode API keys - Use environment variables
Validate inputs - Check user-provided data before processing
Use subprocess safely - Never use shell=True
Pin dependencies - Specify exact versions in requirements.txt

Step 5: Test Your Skill

# tests/test_weather.py
import pytest
from main import fetch_weather

def test_fetch_weather_success():
    result = fetch_weather("London")
    assert "temperature" in result
    assert result["temperature"] > -50

Step 6: Publish Your Skill

Create a GitHub repository
Push your code: git push origin main
Add a clear README with usage examples
Submit to skills.sh or AgentSkillsHub.dev

Next Steps

Read our Security Best Practices guide
Explore 200+ existing skills for inspiration
Join the Agent Skills community on Discord