heilcheng/awesome-agent-skills: Curated AI Agent Skills Directory

heilcheng/awesome-agent-skills: Curated AI Agent Skills Directory

Developers are drowning in context. Every new framework, API, and deployment target demands that AI assistants somehow "know" how to interact with it—yet retraining models is prohibitively expensive, and generic prompts produce inconsistent results. The emerging solution is agent skills: lightweight, portable instruction files that teach AI assistants new capabilities on demand. The heilcheng/awesome-agent-skills repository, maintained by Hailey Cheng (Cheng Hei Lam), has become the definitive community-curated index for this ecosystem, tracking 200+ verified skills across platforms like Claude, Copilot, Codex, and Gemini CLI.

What is heilcheng/awesome-agent-skills?

heilcheng/awesome-agent-skills is a community-curated directory of SKILL.md files—plain-text instruction bundles that teach AI assistants how to perform specific tasks without model retraining or code execution. The repository serves as both a discovery hub and a quality standard for the growing agent skills ecosystem.

With 5,979 GitHub stars, 558 forks, and an MIT License, the project reflects substantial community traction. The codebase is primarily TypeScript, and the repository remains actively maintained with the last commit dated April 5, 2026. The project offers multilingual documentation including English, Traditional Chinese, Simplified Chinese, Japanese, Korean, and Spanish.

Unlike bulk-generated skill repositories, this collection emphasizes real-world skills created and used by actual engineering teams. Skills are compatible with Claude Code, Claude.ai, Codex, Antigravity, Gemini CLI, Cursor, GitHub Copilot, Windsurf, and additional platforms. The repository also maintains a live browsable directory at agent-skill.co.

The maintainer, Hailey Cheng, is accessible via LinkedIn, X @haileyhmt, and haileycheng@proton.me, indicating sustained personal investment in the project's quality and growth.

Key Features

Platform-Agnostic Skill Discovery The repository indexes skills across nine major AI platforms: Claude Code, Claude.ai, Codex, GitHub Copilot, VS Code, Antigravity, Kiro, Gemini CLI, and Junie. Each entry includes direct documentation links and installation paths, eliminating the fragmentation typically encountered when hunting for platform-specific resources.

Verified Quality Standards Contributed skills must meet documented criteria: clear instructions, focused scope, working examples, honest trade-off documentation, and a 500-line limit on SKILL.md files for optimal agent performance. This constraint prevents the context-bloat that degrades agent responsiveness.

Multiple Discovery Mechanisms The repository integrates with three discovery tools: the SkillsMP Marketplace (automatic GitHub indexing with category and star-based filtering), skills.sh (Vercel's popularity leaderboard), and the npx skills CLI for command-line search, installation, and management.

Official and Community Skill Separation Skills are organized into official directories (maintained by platform vendors like Anthropic, OpenAI, Google, Cloudflare, Vercel, HashiCorp, Stripe, and others) and community skills (contributions covering vector databases, marketing, productivity, development/testing, and context engineering).

MCP Server Integration Guidance The repository distinguishes agent skills from Model Context Protocol (MCP) servers while providing configuration examples for tools that support both, such as Claude Desktop's claude_desktop_config.json setup.

Use Cases

Onboarding AI Assistants to Proprietary Workflows Engineering teams can document internal conventions—deployment procedures, code review checklists, API interaction patterns—as reusable skills. This eliminates the repetitive context-setting that consumes token budgets and degrades response quality in long conversations.

Cross-Platform Capability Porting A skill authored for Claude Code can be adapted for Codex or Copilot with minimal modification, since the underlying format is platform-agnostic Markdown^{↗ Smart Converter}. Organizations standardizing on multiple AI tools avoid duplicating institutional knowledge across incompatible systems.

Specialized Domain Acceleration The repository includes deeply specific skills like Trail of Bits' smart contract security toolkit for six blockchains, HashiCorp's Terraform provider scaffolding patterns, and Hugging Face's model training workflows with TRL (SFT, DPO, GRPO). These target practitioners who need reliable, field-tested guidance rather than generic suggestions.

Non-Technical Workflow Automation Skills for product management (46 skills by Dean Peters, 65 by Pawel Huryn), marketing (Corey Haines' SaaS stack), and Google Workspace operations enable knowledge workers without programming backgrounds to automate structured tasks through natural language.

Context Engineering at Scale Skills for context compression, memory systems, and graph-based data structures address the fundamental limitation of finite context windows in current-generation models—particularly relevant for [INTERNAL_LINK: long-context LLM optimization] workflows involving 100+ file repositories.

Installation & Setup

No repository installation is required to use the directory itself. To use skills with your AI agent, follow the platform-specific paths documented in the repository:

Claude Code

# Add a skill directly from GitHub
/skills add <github-url>

# Or install locally
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 to your query.

Claude.ai

Paste the raw SKILL.md URL directly into a new conversation. Claude automatically activates relevant skills based on task detection.

Codex / OpenAI

# Use the built-in skill installer
$skill-installer linear

# Or use the skill-creator skill for custom development
$skill-creator

Restart Codex after installing skills to ensure they're picked up.

VS Code / GitHub Copilot

Skills reside in directories containing a SKILL.md file at these locations:

• .github/skills/ — Recommended for all new skills
• .claude/skills/ — Legacy location, still supported

npx skills CLI (Cross-Platform)

# Search for skills
npx skills find [query]

# Install from GitHub shorthand, full URL, or local path
npx skills add <owner/repo>

# Manage installed skills
npx skills list                    # List installed skills
npx skills check                   # Check for available updates
npx skills update                  # Upgrade all skills
npx skills remove [skill-name]     # Uninstall skills

MCP Server Configuration (Claude Desktop)

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop"]
    }
  }
}

Real Code Examples

Basic SKILL.md Structure

The repository provides this template for skill creation:

---
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]

The frontmatter name and description fields are required. The name must be lowercase with hyphens for spaces. The body contains Markdown instructions that the agent parses like a human reading a guide—no executable code, just structured natural language.

MCP Server Skill (Python^{↗ Bright Coding Blog})

For skills requiring external data access, the repository documents this FastMCP pattern:

# pip install fastmcp
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()

This bridges the gap between instruction-based skills and executable tooling: the skill file teaches the agent when to invoke the MCP server, while the server itself handles the actual API or database interaction.

Skill Directory Layout

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

The repository emphasizes that skills are instructions, not code—the AI reads and follows them, but does not execute them directly. This distinction matters for security-conscious environments where arbitrary code execution is prohibited.

Advanced Usage & Best Practices

Size Discipline: The 500-line SKILL.md limit is not arbitrary. Exceeding it degrades agent retrieval accuracy and increases latency. Complex workflows should decompose into multiple focused skills rather than monolithic guides.

Version Pinning: When referencing skills in production workflows, pin to specific commits rather than main branches. The repository does not enforce semantic versioning on community contributions, so reproducibility requires explicit references.

Hybrid MCP + Skill Architectures: The most robust production setups combine skills (for workflow logic) with MCP servers (for tool access). The repository's documentation of both patterns, without conflating them, supports this architecture.

Context Engineering Skills: For repositories exceeding 100 files, consider the recursive decomposition and memory system skills indexed in the community section. These address the fundamental mismatch between large codebases and finite context windows.

Contribution Hygiene: Before submitting skills, verify they actually work with the target agent. The repository's CONTRIBUTING.md mandates this testing, and the maintainer actively enforces quality standards that prevent the dilution seen in less-curated awesome lists.

Comparison with Alternatives

The primary trade-off: heilcheng/awesome-agent-skills sacrifices depth in any single platform for breadth and cross-platform portability. Teams heavily invested exclusively in Claude may find platform-specific resources more granular, while multi-platform organizations benefit from the unified indexing and consistent quality standards.

FAQ

What's the difference between agent skills and fine-tuning? Fine-tuning permanently modifies model weights; skills are portable instruction files you can update or swap without touching the AI itself.

Do skills execute code on my machine? No. Skills are plain-text instructions—Markdown files the AI reads like a guide. No executable code runs unless you separately configure MCP servers.

Which AI tools support these skills? Claude (Code and web), GitHub Copilot, VS Code, Codex, Antigravity, Gemini CLI, Kiro, and Junie. Support varies by platform—check the compatibility table in the repository.

Are skills free to use? The skill files themselves are free. You need an AI subscription (Claude Pro, Copilot, etc.) for the agent to read and follow them.

How do I evaluate skill safety? Every skill is a public GitHub repository. Read the full SKILL.md before loading, check star counts and last update dates, and verify the author's credibility.

Can non-developers create skills? Yes. Skills require plain English, not code. No terminal or GitHub account needed for basic usage—just paste a skill URL into Claude.ai.

What's the relationship between skills and MCP? Skills teach the AI how to do something; MCP helps it access external tools. They complement each other—see the repository's MCP configuration examples.

Conclusion

heilcheng/awesome-agent-skills addresses a genuine infrastructure gap in the AI assistant ecosystem: the need for portable, verifiable, and maintainable capability extensions that don't require model retraining or vendor lock-in. With nearly 6,000 stars, active maintenance, and quality standards enforced by a named maintainer, it has emerged as the most credible central index for this rapidly evolving format.

The resource suits multi-platform engineering teams, AI tool evaluators, and practitioners building production workflows who need reliable skill discovery rather than hype-driven recommendations. Individual developers deep in a single platform may find vendor-specific resources more granular, but the cross-platform portability and curation discipline here are unmatched.

Browse the live directory at agent-skill.co or explore the source at https://github.com/heilcheng/awesome-agent-skills.