Agent Skills

Thoughts and notes on the topic.

What Are Agent Skills?

Think of Agent Skills as "how-to guides" for AI assistants. Instead of the AI needing to know everything upfront, skills let it learn new abilities on the fly, like giving someone a recipe card instead of making them memorize an entire cookbook.

Skills are simple text files (called SKILL.md) that teach an AI how to do specific tasks. When you ask the AI to do something, it finds the right skill, reads the instructions, and gets to work.

How It Works

Skills load in three stages:

  1. Browse - The AI sees a list of available skills (just names and short descriptions)
  2. Load - When a skill is needed, the AI reads the full instructions
  3. Use - The AI follows the instructions and accesses any helper files

Why This Matters

Skills are instructions, not code. The AI reads them like a human would read a guide, then follows the steps.

Compatible Agents

The following platforms have documented support for Agent Skills:

Agent Documentation
Claude Code code.claude.com/docs/en/skills
Claude.ai support.claude.com
Codex (OpenAI) developers.openai.com
GitHub Copilot docs.github.com
VS Code code.visualstudio.com

Skill List

Official Claude Skills (Document Processing)

Claude provides built-in skills for common document types:

Skill Description Source
docx Create, edit, analyze Word documents with tracked changes anthropics/skills
xlsx Spreadsheet manipulation: formulas, charts, data transformations anthropics/skills
pptx Read, generate, and adjust slides, layouts, templates anthropics/skills
pdf Extract text, tables, metadata from PDFs anthropics/skills

Official OpenAI Codex Skills

Codex supports skills at different scopes:

Skill Scope Location Suggested Use
REPO $CWD/.codex/skills Skills relevant to a working folder (e.g., microservice or module)
REPO $CWD/../.codex/skills Skills for shared areas in parent folders
REPO $REPO_ROOT/.codex/skills Root skills for everyone using the repository
USER $CODEX_HOME/skills (default: ~/.codex/skills) Personal skills that apply to any repository
ADMIN /etc/codex/skills SDK scripts, automation, and default admin skills
SYSTEM Bundled with Codex Built-in skills like skill-creator and plan

Official HuggingFace Skills

Skill Description Source
hf_dataset_creator Prompts, templates, and scripts for creating structured training datasets huggingface/skills
hf_model_evaluation Instructions plus utilities for orchestrating evaluation jobs, generating reports, and mapping metrics huggingface/skills
hf-llm-trainer Comprehensive training skill with guidance, helper scripts, cost estimators huggingface/skills
hf-paper-publisher Tools for publishing and managing research papers on Hugging Face Hub huggingface/skills

Community Skills

Community-maintained skills and collections (verify before use):

Skill Collections

Repository Description
anthropics/skills Official Anthropic collection (document editing, data analysis)
openai/skills Official OpenAI Codex skills catalog
huggingface/skills HuggingFace skills (compatible with Claude, Codex, Gemini)
skillcreatorai/Ai-Agent-Skills SkillCreator.ai collection with CLI installer
karanb192/awesome-claude-skills 50+ verified skills for Claude Code and Claude.ai
shajith003/awesome-claude-skills Skills for specialized capabilities
GuDaStudio/skills Multi-agent collaboration skills
DougTrajano/pydantic-ai-skills Pydantic AI integration
OmidZamani/dspy-skills Skills for DSPy framework
ponderous-dustiness314/awesome-claude-skills Document editing, data analysis, project management
hikanner/agent-skills Curated Claude Agent Skills collection
gradion-ai/freeact-skills Freeact agent library skills
gotalab/skillport Skills distribution via CLI or MCP
mhattingpete/claude-skills-marketplace Git, code review, and testing skills

Document Processing

Skill Description
Markdown to EPUB Converts markdown documents into professional EPUB ebook files

Development & Code Tools

Skill Description
aws-skills AWS development with CDK best practices
D3.js Visualization D3 charts and interactive data visualizations
Playwright Automation Browser automation for testing web apps
iOS Simulator Interact with iOS Simulator for testing
Swift Concurrency Migration Swift Concurrency Migration guide
Obsidian Plugin Obsidian.md plugin development
Stream Coding Stream Coding methodology

Data & Analysis

Skill Description
CSV Summarizer Analyze CSV files and generate insights with visualizations

Integration & Automation

Skill Description
Dev Browser Web browser capability for agents
Sheets CLI Google Sheets CLI automation
Spotify Skill Spotify API integration

Collaboration & Project Management

Skill Description
git-pushing Automate git operations and repository interactions
review-implementing Evaluate code implementation plans
test-fixing Detect failing tests and propose fixes

Security & Systems

Skill Description
computer-forensics Digital forensics analysis and investigation
Threat Hunting Hunt for threats using Sigma detection rules

Advanced & Research

Skill Description
Context Engineering Context engineering techniques
Pomodoro System Skill System Skill Pattern (skills that remember & improve)
Mind Cloning Mind cloning with LLM skills

Official Tutorials and Guides

Claude and Anthropic

GitHub Copilot

Model Context Protocol (MCP)

Using Skills

Using Skills in Claude.ai

  1. Click the skill icon in your chat interface.
  2. Add skills from the marketplace or upload custom skills.
  3. Claude automatically activates relevant skills based on your task.

Using Skills in Claude Code

Place the skill in your configuration directory:

mkdir -p ~/.claude/skills/
cp -r skill-name ~/.claude/skills/

Verify skill metadata:

head ~/.claude/skills/skill-name/SKILL.md

The skill loads automatically and activates when relevant.

Using Skills in Codex

Create a skill:

Use the built-in $skill-creator skill in Codex. Describe what you want your skill to do, and Codex will bootstrap it for you.

If you install $create-plan (experimental) with $skill-installer create-plan, Codex will create a plan before writing files.

You can also create a skill manually by creating a folder with a SKILL.md file:

---
name: skill-name
description: Description that helps Codex select the skill
metadata:
  short-description: Optional user-facing description
---

Skill instructions for the Codex agent to follow when using this skill.

Install new skills:

Download skills from GitHub using the $skill-installer skill:

$skill-installer linear

You can also prompt the installer to download skills from other repositories. After installing a skill, restart Codex to pick up new skills.

Using Skills in VS Code

Skills are stored in directories with a SKILL.md file. VS Code supports skills in two locations:

Create a skill:

  1. Create a .github/skills directory in your workspace
  2. Create a subdirectory for your skill (e.g., .github/skills/webapp-testing)
  3. Create a SKILL.md file with the following structure:
---
name: skill-name
description: Description of what the skill does and when to use it
---

# Skill Instructions

Your detailed instructions, guidelines, and examples go here...
  1. Optionally, add scripts, examples, or other resources to your skill's directory

Using Skills in Copilot CLI

Adding skills to your repository:

  1. Create a .github/skills directory (skills in .claude/skills are also supported)
  2. Create a subdirectory for your skill (e.g., .github/skills/webapp-testing)
  3. Create a SKILL.md file with your skill's instructions

SKILL.md structure:

Example SKILL.md:

---
name: github-actions-failure-debugging
description: Guide for debugging failing GitHub Actions workflows.
---

To debug failing GitHub Actions workflows:

1. Use `list_workflow_runs` to look up recent workflow runs
2. Use `summarize_job_log_failures` to get an AI summary of failed jobs
3. Use `get_job_logs` for full detailed failure logs if needed
4. Try to reproduce the failure in your environment
5. Fix the failing build

When performing tasks, Copilot decides when to use skills based on your prompt and the skill's description. The SKILL.md file is injected into the agent's context.

Using MCP Servers (Claude Desktop)

Edit your configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Example Configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop"
      ]
    }
  }
}

Creating Skills

Skills are instruction bundles that tell the agent how to perform specific tasks. They are not executable code by default.

Skill Structure

skill-name/
├── SKILL.md          # Required: Instructions and metadata
├── scripts/          # Optional: Helper scripts
├── templates/        # Optional: Document templates
└── resources/        # Optional: Reference files

Basic SKILL.md Template

---
name: my-skill-name
description: A clear description of what this skill does.
---

# My Skill Name

Detailed description of the skill's purpose.

## When to Use This Skill

- Use case 1
- Use case 2

## Instructions

[Detailed instructions for the agent on how to execute this skill]

## Examples

[Real-world examples]

MCP Server Example (Python)

For skills that need to connect to external data sources, you can create an MCP server:

pip install fastmcp

server.py:

from fastmcp import FastMCP

mcp = FastMCP("My Server")

@mcp.tool()
def hello_world(name: str = "World") -> str:
    """A simple tool that says hello."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

Community Resources

LangChain Tools

Frequently Asked Questions

What are Agent Skills?

Agent Skills are instruction files that teach AI assistants how to do specific tasks. Think of them as "how-to guides" that the AI reads and follows. They only load when needed, so the AI stays fast and focused.

How are Agent Skills different from fine-tuning?

Fine-tuning permanently changes how an AI thinks (expensive and hard to update). Agent Skills are just instruction files, you can update, swap, or share them anytime without touching the AI itself.

What's the difference between Agent Skills and MCP?

They do different things and work great together:
- Agent Skills = teach the AI how to do something (workflows, best practices)
- MCP = help the AI access things (APIs, databases, external tools)

Which AI tools support Agent Skills?

Currently supported: Claude (Claude.ai and Claude Code), GitHub Copilot, VS Code, and others. The list is growing as more tools adopt the standard.

Do Agent Skills run code?

No. Skills are just text instructions, the AI reads and follows them like a recipe. If you need to run actual code, you'd use something like MCP servers alongside skills.

How do I create my first Agent Skill?

  1. Create a SKILL.md file with a name and description at the top
  2. Write clear, step-by-step instructions in the file
  3. Put it in your .github/skills/ or .claude/skills/ folder
  4. Test it out!

Full guide: How to create custom skills

Contributing

This repository follows the Agent Skills open development model. Contributions are welcome from the broader ecosystem. When contributing:

License

MIT License - see LICENSE file for details.

References

The principles in these skills are derived from research and production experience at leading AI labs and framework developers.

Tags: ai   agent   skills  

Last modified 15 January 2026