Agent Skills: Complete Getting-Up-To-Speed Guide

15-minute overview of agent SKILLS ecosystem, including links to marketplaces and repositories with over 25,000+ reusable ready-to-go skills

Practical overview of the whole Agent skills mechanism and the rapidly expanding ecosystem: where skills live across Claude surfaces (Claude.ai, Claude Code, API, SDK), why the open Agent Skills standard makes them increasingly portable across other agent tools (including coding agents), and where to find the huge supply of ready-made packs and directories (25k+).

Part 1: Overview — What Skills Actually Are

Skills are folders of instructions, scripts, and resources that Claude (and other AI agents) can discover and load dynamically to improve performance on specialized tasks. Think of them as onboarding documents for an AI — procedural knowledge packaged into portable, version-controlled units.

The key mental model: skills are prompt injection, not code execution. When Claude decides a skill is relevant, it loads the skill’s instructions into its context window, which modifies how it reasons about and approaches the task. Skills can also include executable scripts, templates, and reference files, but the core mechanism is context injection.

The Anatomy of a Skill

At minimum, a skill is a directory with a SKILL.md file:

my-skill/
├── SKILL.md           # Main instructions (required)
├── references/        # Supplemental docs (optional)
│   └── REFERENCE.md
├── scripts/           # Executable code (optional)
│   └── process.py
├── templates/         # Templates to fill (optional)
│   └── template.md
└── examples/          # Example outputs (optional)
    └── sample.md

The SKILL.md must have YAML frontmatter:

yaml

---
name: my-skill-name          # 64 chars max
description: >-              # 200 chars max — this is CRITICAL
  Clear description of what this skill does and when Claude
  should use it. Claude uses this to decide when to invoke.
license: Apache-2.0          # Optional
metadata:                    # Optional
  author: your-name
  version: "1.0"
---

# Skill Instructions

Your detailed instructions, guidelines, and examples here...

Progressive Disclosure Architecture

This is the key architectural insight:

1. Frontmatter only (~50-100 tokens per skill) — loaded at startup for routing decisions

2. SKILL.md body — loaded when Claude decides the skill is relevant

3. Reference files — loaded on-demand only when specific sub-tasks need them

This means you can have many skills registered without blowing up context. Keep SKILL.md under 500 lines / 5000 tokens. Move detailed reference material to separate files.

---

Part 2: Where Skills Live — The Four Surfaces

Skills work across four Claude surfaces, each with different mechanics:

1. Claude.ai (Web/Desktop/Mobile)

• Pre-built skills: Document creation (docx, xlsx, pptx, pdf) work automatically behind the scenes

• Custom skills: Upload as .zip via Settings > Features > Skills

• Scope: Per-user only — not shared org-wide, no admin management

• Requires: Pro, Max, Team, or Enterprise plan + code execution enabled

• Network: Varies by user/admin settings (full, partial, or none)

• Packages: Only pre-installed packages available; no runtime installs

2. Claude Code (Terminal)

• Personal skills: ~/.claude/skills/ — available in all sessions

• Project skills: .claude/skills/ in project root — version-controlled with the repo

• Plugin skills: Installed via the plugin marketplace system

• Discovery: Automatic — Claude Code scans these directories

• Network: Full access (same as any terminal program)

• Packages: Can install from PyPI, npm at runtime

• Subagents: Skills can fork into Explore, Plan, or custom subagent types

• Priority: enterprise > personal > project (when names conflict)

• Monorepo support: Nested .claude/skills/ in subdirectories are auto-discovered

3. Claude API (Developer Platform)

• Skills API: /v1/skills endpoints for CRUD operations

• Pre-built: Reference by skill_id (e.g., pptx, xlsx)

• Custom: Upload via API, shared org-wide

• Requires: Beta headers: code-execution-2025-08-25

• Management: Via Claude Console or API

• Packages: Only pre-installed; no runtime installation

4. Claude Agent SDK

• Filesystem-based: Place in project directories

• Auto-discovered: SDK scans at startup

• Same format: Standard SKILL.md in directories

---

Part 3: The Open Standard — Agent Skills Specification

In December 2025, Anthropic released Agent Skills as an open standard at agentskills.io. This is the same playbook as MCP (Model Context Protocol): establish an open ecosystem, win by being best at using it.

Adoption (as of early 2026)

The standard has been adopted by:

• Claude Code (native)

• OpenAI Codex CLI & ChatGPT

• GitHub Copilot (VS Code, CLI, coding agent)

• Cursor

• Windsurf

• Gemini CLI

• Amp, Goose, Roo Code, Trae, OpenCode, Letta

This means skills you write are portable. A skill created for Claude Code works in Cursor, Copilot, Codex, etc. — write once, use everywhere.

Specification Resources

ResourceURLSpec (full)agentskills.io/specificationIntegration guideagentskills.io/integrate-skillsGitHub orggithub.com/agentskillsReference SDK (skills-ref)Python library for validation

---

Part 4: Finding & Installing Third-Party Skills

The ecosystem has exploded. Here’s what exists:

Official Anthropic Repositories

github.com/anthropics/skills → Official skill examples + production document skills (docx, pdf, pptx, xlsx). Apache 2.0 for examples; source-available for doc skills. Functions as a Claude Code Plugin marketplace.

github.com/anthropics/claude-plugins-official → Official plugin marketplace directory. Third-party partners can submit.

github.com/anthropics/knowledge-work-plugins → 11 role-based plugins (Sales, Support, Product Management, Finance, Data, etc.) with skills, commands, and MCP connectors. Open source.

github.com/anthropics/life-sciences → Life sciences MCP servers and skills (PubMed, BioRender, etc.)

Community Skill Directories & Marketplaces

skills.sh → Primary distribution hub. npx skills add <package>. Leaderboard, multi-platform.

skillsmp.com → Independent directory, aggregates from GitHub. Min 2-star filter.

skillhub.club → 20K+ skills with AI-evaluated quality ratings. Has a playground.

hub.skild.sh → Another community registry

agentskill.sh → 25K+ skills directory, browseable by category/platform

Key Community Projects

obra/superpowers → Complete software dev workflow: brainstorm → plan → TDD → implement → review. 20+ battle-tested skills. The gold standard for skill composition. Install: /plugin marketplace add obra/superpowers-marketplace then /plugin install superpowers@superpowers-marketplace

obra/superpowers-skills → Community-editable extension to Superpowers

obra/superpowers-lab → Experimental skills (tmux for interactive commands, etc.)

travisvn/awesome-claude-skills → Curated awesome-list of skills, resources, and tools

numman-ali/openskills → Universal skills loader. npx openskills install anthropics/skills. Works across Claude Code, Cursor, Windsurf, Aider, Codex, etc.

vercel-labs/agent-skills → Vercel’s official skills: React, Next.js, React Native patterns + Vercel deploy skill

qufei1993/skills-hub → Desktop app: “Install once, sync everywhere” — manages skills across multiple AI tools

inference.sh skills → 150+ cloud AI app skills (image gen, video, TTS, search) via infsh CLI

Installing Skills in Claude Code

bash

# Register the official Anthropic marketplace
/plugin marketplace add anthropics/skills

# Install specific plugin packs
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

# Register Superpowers marketplace
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Install from Vercel's skills.sh
npx skills add vercel-labs/agent-skills

# Install with OpenSkills (universal, cross-platform)
npx openskills install anthropics/skills

---

Part 5: Building Your Own Skills — Best Practices

Design Principles

1. Single-purpose: “SEO optimization for blog posts” is good. “Content marketing helper” is too broad. “Add meta descriptions” is too narrow.

2. Description is king: Claude routes based on the description field. Vague = missed triggers. Overly generic = false triggers. Be specific about when and what.

3. Progressive disclosure: Keep SKILL.md lean. Reference files for deep details. Scripts for deterministic steps.

4. Imperative instructions: Write as if onboarding a smart junior engineer. Be explicit about steps, inputs, outputs.

5. Include examples: Show expected inputs and outputs. Show what “good” looks like.

6. Token budget: Metadata ~50-100 tokens. Full SKILL.md < 5000 tokens. Reference files on-demand.

The Description Field — Most Important 200 Characters You’ll Write

Bad:

yaml

description: Helps with code

Good:

yaml

description: >-
  Generate FastAPI backend with React+Vite frontend, Tailwind, shadcn/ui,
  and OpenAI integration. Use when asked to scaffold a full-stack AI app.

Claude uses semantic matching, not keyword matching — but vague descriptions still reduce accuracy.

Skill Structure Patterns

Pattern 1: Instructions-only (simplest)

my-skill/
└── SKILL.md     # All instructions in one file

Pattern 2: Instructions + References

brand-guidelines/
├── SKILL.md           # Overview + when to apply
└── references/
    ├── colors.md      # Detailed color specs
    ├── typography.md   # Font rules
    └── voice.md       # Tone of voice guide

Pattern 3: Instructions + Scripts (executable)

data-pipeline/
├── SKILL.md
├── scripts/
│   ├── validate.py
│   └── transform.sh
└── templates/
    └── output-schema.json

Pattern 4: Full production skill (like the built-in docx skill)

docx/
├── SKILL.md
├── LICENSE.txt
├── scripts/
│   ├── office/
│   │   ├── soffice.py
│   │   ├── unpack.py
│   │   └── validate.py
│   └── accept_changes.py
├── references/
│   └── REFERENCE.md
└── examples/
    └── sample-doc.docx

Creating Skills with the Skill-Creator

Claude has a built-in skill-creator skill (available in claude.ai and as a plugin). The workflow:

1. Tell Claude “I want to create a skill for X”

2. It interviews you about the workflow

3. Generates the SKILL.md and folder structure

4. Creates test prompts

5. Runs Claude-with-skill on them

6. You evaluate results

7. Iterate until satisfied

You can also use the eval/benchmark system for more rigorous testing:

• Eval mode: Test individual prompts, compare with/without skill

• Improve mode: Iterative optimization with blind A/B comparisons

• Benchmark mode: Standardized measurement with variance analysis (3x runs per config)

Claude Code-Specific Features

In Claude Code, skills gain extra powers via frontmatter:

yaml

---
name: deep-research
description: Research a topic thoroughly
context: fork          # Runs in a forked subagent
agent: Explore         # Uses the Explore agent (read-only tools)
---

Options for context:

• Default (omitted): Claude loads it when relevant

• fork: Runs as a separate subagent task

Options for agent:

• Explore: Read-only codebase exploration

• Plan: Planning-focused

• Custom: Any subagent from .claude/agents/

Skills can also be invoked as slash commands:

• .claude/skills/review/SKILL.md creates /review

• (This replaced the older .claude/commands/ system)

---

Part 6: Systematizing Skills Across Projects

This is where your engineering background pays off. Here’s the architecture for managing skills at scale:

Recommended Repository Structure

your-skills-monorepo/          # GitHub repo — your personal skills library
├── .claude-plugin/
│   └── marketplace.json       # Makes this a Claude Code marketplace
├── skills/
│   ├── product-spec/          # Product specification generation
│   │   ├── SKILL.md
│   │   └── templates/
│   │       └── spec-template.md
│   ├── api-design/            # API-first design workflow
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── openapi-patterns.md
│   ├── startup-mvp/           # Your MVP scaffolding workflow
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── scaffold.sh
│   ├── code-review/           # Your code review standards
│   │   └── SKILL.md
│   └── deploy-pipeline/       # Your deployment workflow
│       ├── SKILL.md
│       └── scripts/
│           └── deploy.sh
├── plugins/
│   ├── product-dev/           # Plugin: groups related skills
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   │       ├── product-spec/
│   │       └── api-design/
│   └── devops/
│       └── ...
└── README.md

Git + GitHub Workflow

bash

# Register your personal marketplace in Claude Code
/plugin marketplace add your-github-username/your-skills-repo

# Install specific plugin packs
/plugin install product-dev@your-skills-marketplace

# Update skills (pull latest from Git)
/plugin update product-dev

Version your skills — use Git tags, a CHANGELOG, and semver in the metadata field. When you improve a skill, bump the version.

Obsidian Integration Strategy

Obsidian is great as the authoring and knowledge management layer that feeds into your Git-managed skills:

obsidian-vault/
├── Skills/                    # Mirror of your Git skills repo
│   ├── product-spec/
│   │   └── SKILL.md          # Edit here, push to Git
│   └── ...
├── Workflows/                 # Document your processes before turning them into skills
│   ├── how-i-deploy.md
│   ├── how-i-do-code-review.md
│   └── how-i-spec-a-feature.md
├── Templates/                 # Obsidian templates that also serve as skill templates
└── Skill-Ideas/               # Backlog of skills to build
    └── kanban.md

Workflow:

1. Document your workflow in Obsidian (Workflows/)

2. When it’s repeatable enough, draft the SKILL.md in Obsidian (Skills/)

3. Use Obsidian Git plugin to push to your skills GitHub repo

4. Test via Claude Code with your marketplace

5. Iterate

Useful Obsidian plugins:

• Obsidian Git: Auto-sync your vault to GitHub

• Templater: Template system for consistent SKILL.md structure

• Kanban: Track skill development pipeline

• Dataview: Query across your skills for metadata/status

Cross-Project Automation

For your product ideas, structure each project to inherit your skills:

project-alpha/
├── .claude/
│   └── skills/               # Project-specific skills
│       └── alpha-domain/
│           └── SKILL.md
├── .claude/settings.json     # Project config pointing to your marketplace
└── src/

Your personal skills (~/.claude/skills/) apply everywhere. Your marketplace skills (via plugin) apply when installed. Your project skills (.claude/skills/) apply only in that project.

This three-tier system lets you:

• Keep universal skills (coding standards, review processes) personal

• Keep shared skills (product frameworks, deploy pipelines) in your marketplace

• Keep domain-specific skills (this project’s API patterns) in the project

---

Part 7: Getting-Up-To-Speed - Practical Plan

Here I outline a practical approach on how to multiply your productivity by integrating agentic skills into your day-to-day workflow with Claude, Codex, or any other AI agent tool of your choice (using Claude as an example).

Foundation (2-3 hours)

Understand the landscape

• Read the Agent Skills specification (15 min)

• Read Anthropic’s blog post introducing skills (10 min)

• Read the how to create skills guide (15 min)

• Read the Claude Code skills docs (15 min)

• Read Lee Han Chung’s deep dive on skill architecture (20 min)

Explore existing skills

• Browse github.com/anthropics/skills — read 3-4 example SKILL.md files to see patterns

• Browse skills.sh and skillsmp.com to see what the community has built

• Install Superpowers in Claude Code: /plugin marketplace add obra/superpowers-marketplace + /plugin install superpowers@superpowers-marketplace

• Read Jesse Vincent’s blog post on Superpowers — this is the best practical write-up on skill composition

• Browse travisvn/awesome-claude-skills for curated resources

Try it hands-on

• Ask Claude (in claude.ai or Claude Code) to “create a skill for [something you do repeatedly]” — use the skill-creator

• Test the generated skill on a real task

• Iterate once or twice based on results

Build Your System (3-4 hours)

Set up your skills infrastructure

• Create a GitHub repo for your personal skills (your-username/claude-skills)

• Add a marketplace.json to make it a Claude Code marketplace

• Set up Obsidian vault with the Skills/ and Workflows/ structure described above

• Install the Obsidian Git plugin and connect to your skills repo

• Create a SKILL.md template in Obsidian Templater

Build your first 3 skills Start with workflows you repeat across projects:

1. Your project scaffolding workflow — how you set up a new project (tech stack, folder structure, CI, etc.)

2. Your code review checklist — your standards for reviewing code

3. Your product spec process — how you go from idea to spec

For each:

1. Document the workflow in Obsidian Workflows/

2. Draft the SKILL.md

3. Push to Git

4. Register your marketplace in Claude Code

5. Test on a real task

6. Iterate

Day 5: Explore the API surface

• Read the Skills API docs

• Try uploading a custom skill via the API

• Understand the /v1/skills endpoints for programmatic management

Scale & Parallelize (3-4 hours)

Build product-specific skills For each of your product ideas, create:

• Domain knowledge skill (what this product does, its entities, its terminology)

• Architecture skill (your preferred stack, patterns, conventions for this product)

• Testing skill (how you want tests structured for this product)

Explore advanced patterns

• Read the MCP builder skill — skills + MCP is a powerful combination

• Try context: fork and subagent delegation in Claude Code

• Explore anthropics/knowledge-work-plugins for the plugin architecture pattern

• Install openskills (npx openskills install anthropics/skills) for cross-tool skill management

Automate and refine

• Set up GitHub Actions to validate your skills on push (use skills-ref Python library)

• Create a “meta-skill” that helps you create new skills faster (or use the built-in skill-creator as a base)

• Document your skills system in your Obsidian vault so future-you (and future-Claude) can maintain it

---

Part 8: Documentation

Links to useful documentation sources and additional reading.

Agent Skills Spec → agentskills.io/specification

Claude Code Skills Docs → code.claude.com/docs/en/skills

API Skills Docs → platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

Create Custom Skills → support.claude.com/en/articles/12512198

How to Create Skills (blog) → claude.com/blog/how-to-create-skills-key-steps-limitations-and-examples

Jesse Vincent’s Superpowers blog → blog.fsck.com/2025/10/09/superpowers/

Simon Willison on Skills → simonwillison.net/2025/Dec/19/agent-skills/

Lee Han Chung Architecture Deep Dive → leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/

---

Part 9: Key Takeaways for Your Use Case

Given that you want to accelerate and parallelize development of multiple product ideas, here’s what matters most:

1. Skills are your force multiplier. Each product idea should have a domain skill that encodes its terminology, architecture decisions, and patterns. When you switch between projects, Claude instantly “knows” the context.

2. The open standard means you’re not locked in. Skills you write for Claude Code work in Cursor, Copilot, Codex, etc. Invest in the format confidently.

3. Superpowers is your starting point for dev workflow. Install it immediately. It enforces brainstorm → plan → TDD → implement → review, which is exactly the discipline you need when parallelizing across multiple products.

4. Your personal marketplace is your moat. As you encode your 20+ years of engineering experience into skills, you’re creating a reusable library that makes every future project faster. This compounds.

5. MCP + Skills is the power combo. Skills tell Claude how to do things. MCP servers give Claude tools to do things. Combined, you get agents that follow your workflows using your tools.

6. Start with what you repeat, not what’s clever. Your first skills should capture boring, repeated workflows — project setup, code review, deployment, spec writing. These have the highest ROI.

7. Version everything in Git. Skills are just markdown and scripts. They belong in version control. Use your Obsidian vault as the authoring layer, Git as the source of truth.