Skip to main content
Profile picture
AI Agent Skills are a productivity multiplier for any professional.

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

• 11 min • 2,443 words
AI Agents Claude Code Skills LLMs Productivity

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

Part 1: Overview — What Skills Actually Are

Skills are folders of instructions, scripts, and resources that Claude (and other AI agents like OpenAI’s Codex and GitHub’s Copilot) 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

While exact file naming varies between agents, the principals of how skills are structured are the same. Here we use Claude’s structure as an example.

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:

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

ResourceURL
Spec (full)agentskills.io/specification
Integration guideagentskills.io/integrate-skills
GitHub orggithub.com/agentskills
Reference 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

RepositoryWhat’s There
github.com/anthropics/skillsOfficial 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-officialOfficial plugin marketplace directory. Third-party partners can submit.
github.com/anthropics/knowledge-work-plugins11 role-based plugins (Sales, Support, Product Management, Finance, Data, etc.) with skills, commands, and MCP connectors. Open source.
github.com/anthropics/life-sciencesLife sciences MCP servers and skills (PubMed, BioRender, etc.)

Community Skill Directories & Marketplaces

PlatformURLNotes
skills.sh (Vercel)skills.shPrimary distribution hub. npx skills add <package>. Leaderboard, multi-platform.
SkillsMPskillsmp.comIndependent directory, aggregates from GitHub. Min 2-star filter.
SkillHubskillhub.club20K+ skills with AI-evaluated quality ratings. Has a playground.
Skild Hubhub.skild.shAnother community registry
agentskill.shagentskill.sh25K+ skills directory, browseable by category/platform

Key Community Projects

ProjectWhat It Does
obra/superpowersComplete 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-skillsCommunity-editable extension to Superpowers
obra/superpowers-labExperimental skills (tmux for interactive commands, etc.)
travisvn/awesome-claude-skillsCurated awesome-list of skills, resources, and tools
numman-ali/openskillsUniversal skills loader. npx openskills install anthropics/skills. Works across Claude Code, Cursor, Windsurf, Aider, Codex, etc.
vercel-labs/agent-skillsVercel’s official skills: React, Next.js, React Native patterns + Vercel deploy skill
qufei1993/skills-hubDesktop app: “Install once, sync everywhere” — manages skills across multiple AI tools
inference.sh skills150+ cloud AI app skills (image gen, video, TTS, search) via infsh CLI

Installing in Claude Code

# 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:

description: Helps with code

Good:

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:

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

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

# 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 Plan

Week 1: Foundation (2-3 hours)

Day 1-2: Understand the landscape

Day 3-4: Explore existing skills

Day 5: 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

Week 2: Build Your System (3-4 hours)

Day 1-2: 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

Day 3-4: 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

Week 3: Scale & Parallelize (3-4 hours)

Day 1-2: 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)

Day 3: 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

Day 4-5: 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: Quick Reference — Tools & Services

Official Anthropic

ToolPurposeURL
Claude.ai SkillsUpload custom skills in the web interfaceSettings > Features
Claude Code PluginsInstall/manage skills from marketplaces/plugin commands
Skills APIProgrammatic skill management/v1/skills endpoint
Skills GitHubOfficial examples + document skillsgithub.com/anthropics/skills
Anthropic AcademyLearning resourcesacademy.anthropic.com

Community Tools

ToolWhat It DoesInstall/URL
skills.shSkill directory + installernpx skills add <pkg> / skills.sh
openskillsUniversal cross-platform installernpx openskills install <repo>
Skills Hub DesktopDesktop app for multi-tool syncgithub.com/qufei1993/skills-hub
skills-refPython validation librarypip install skills-ref

Documentation

ResourceURL
Agent Skills Specagentskills.io/specification
Claude Code Skills Docscode.claude.com/docs/en/skills
API Skills Docsplatform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Create Custom Skillssupport.claude.com/en/articles/12512198
How to Create Skills (blog)claude.com/blog/how-to-create-skills-key-steps-limitations-and-examples
Engineering Blog (architecture deep dive)Referenced in the skills blog post
Jesse Vincent’s Superpowers blogblog.fsck.com/2025/10/09/superpowers/
Simon Willison on Skillssimonwillison.net/2025/Dec/19/agent-skills/
Lee Han Chung Architecture Deep Diveleehanchung.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.