Agent Skills: 30 Questions and Answers about the Open Standard for AI Agents

Agent Skills: Specialised Knowledge for AI Agents  

AI models like Claude possess enormous general knowledge – but for specific tasks, they often lack the procedural know-how and organisational context. This is exactly where Agent Skills come in: an open standard that defines modular, file-system-based resources and turns a generalist into a specialist.

Originally developed by Anthropic , the standard is now supported by over 30 tools – including Cursor, Claude Code, VS Code, GitHub Copilot, Roo Code, OpenAI Codex, and many more. This means: a skill created once works cross-platform .

Whether you are using skills for the first time or optimising your enterprise deployment – here you will find 30 well-founded answers, from the basics to advanced edge cases. The Anthropic Cookbook offers a practical introduction .

Table of Contents  

Quick Overview: All 30 Questions  

Click on a question to jump to the detailed answer.

Category 1: Fundamentals and Concepts  

Category 2: Skill Structure and Setup  

Category 3: Creating and developing skills  

Category 4: Using and integrating skills  

Category 5: Security and Enterprise  

Category 6: Advanced Techniques and Edge Cases  

1.1. What are Agent Skills and what are they used for?  

Short answer: Agent Skills are an open standard for reusable, file-system-based resources that provide AI agents with domain-specific expertise – cross-platform, from Claude to Cursor and VS Code.

Detailed explanation:

Agent Skills were originally developed by Anthropic and are now an open standard (agentskills.io) supported by over 30 agent products. According to the official documentation , skills consist of directories containing instructions, executable code, and reference materials. They differ fundamentally from individual prompts because they:

The Anthropic Engineering team describes the approach as an "Onboarding Guide for a new hire": Instead of building fragmented, custom-built agents for every use case, anyone can create their own specialised agents using composable resources (Anthropic Engineering Blog).

The specification on agentskills.io is open to contributions from the entire ecosystem – the associated GitHub repository welcomes community contributions. For tool manufacturers, the specification offers a dedicated guide to integrating skills support into their own agents or IDEs. Additionally, agentskills.io provides a Reference Library that can be used to programmatically validate SKILL.md files and generate them as prompt XML.

1.2. How do skills differ from regular prompts?  

Short answer: Prompts are single-use conversational instructions; skills are persistent, file-system-based modules that load on demand and bundle code, instructions, and resources.

Detailed explanation:

The crucial difference lies in the architecture: Skills exist as directories within the file system. In Claude, the agent interacts with them via Bash commands, whereas in Cursor, they are automatically discovered at startup and can additionally be invoked manually via /skill-name in the agent chat (Cursor Docs). Cursor also offers the option disable-model-invocation: true to make skills available exclusively as a slash command – without automatic triggering.

Daniel Miessler describes the distinction in practical terms: Skills are domain containers (e.g. blogging, research, security), whereas workflows are task procedures that can be nested within skills (Miessler, 2025).

1.3. Which pre-built skills does Anthropic offer?  

Short answer: Four document skills for PowerPoint, Excel, Word, and PDF – ready to use immediately via the Claude API and claude.ai.

Detailed explanation:

These skills demonstrate Claude's "Create Files" feature and use the skills architecture internally to provide Claude with the necessary libraries and processing workflows (Anthropic Platform Docs – Quickstart).

npx skills add https://github.com/anthropics/skills --skill skill-creator

The source code of the pre-built document skills can be viewed in the official anthropics/skills repository on GitHub – with over 94,000 stars, it is the canonical reference for skill authors. The ecosystem is growing rapidly: On skills.sh , find-skills leads the leaderboard with 572,000+ installations, followed by vercel-react-best-practices (214,000+), web-design-guidelines (169,000+), and frontend-design (162,000+). Microsoft's github-copilot-for-azure collection reaches over 2.5 million installations distributed across 18+ skills.

1.4. What does "Progressive Disclosure" mean for Skills?  

Short answer: A three-stage loading model that only pulls relevant information into the context window – comparable to a book that shows the table of contents first, then chapters, then the appendix.

Detailed explanation:

Anthropic's engineering team emphasises: Progressive Disclosure ensures that only relevant content occupies the context window. As Han Lee describes in his analysis, this architecture enables Skills with dozens of reference files, without unused content consuming tokens (Lee, 2025).

1.5. For which use cases are Skills best suited?  

Short answer: Recurring workflows, domain-specific tasks, and team-wide standardisation – wherever you regularly provide Claude with the same context.

Detailed explanation:

Claire Vo emphasises in Lenny's Newsletter that Skills are particularly beneficial when the same instructions are needed regularly – such as a company style guide, a specific reporting format, or a compliance checklist (Vo, 2025).

2.1. How is a SKILL.md file structured?  

Short answer: YAML frontmatter with name and description, followed by a Markdown body with instructions, examples, and reference links.

Detailed explanation:

Every skill requires a SKILL.md file as an entry point. The official documentation defines this structure:

---
name: processing-pdfs
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Use pdfplumber for text extraction:

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
  text = pdf.pages[0].extract_text()

2.2. Which fields are required in the YAML frontmatter?  

Short answer: Two mandatory fields (name, description) plus platform-specific optional fields – Cursor extends the standard with license, compatibility, metadata, and disable-model-invocation.

Detailed explanation:

The official documentation defines explicit restrictions for the name field: The reserved words "anthropic" and "claude" are not allowed, to avoid namespace collisions with official Anthropic skills. Additionally, neither name nor description may contain XML tags – a protective measure against prompt injection via the frontmatter.

The description is the most critical text in the entire skill: Both Claude and Cursor use it to select the right one from potentially hundreds of installed skills. It must cover both the what and the when (Best Practices).

The disable-model-invocation field is now supported by Cursor and Claude Code: This allows you to use skills as classic slash commands – the agent only applies them if you explicitly type /skill-name.

2.3. How do the three levels of skill loading work?  

Short answer: Level 1 (metadata) is always loaded, Level 2 (SKILL.md body) upon trigger, Level 3+ (bundled files/scripts) only when specifically needed.

Detailed explanation:

The skills architecture is based on Claude's VM environment with file system access. On startup, Claude only loads the name and description fields of all skills (~100 tokens per skill) into the system prompt. Only when a request matches a skill does Claude read the complete SKILL.md file via Bash.

Scripts are executed, not loaded: When Claude starts a utility script like validate_form.py, only the output of the script ends up in the context window – not the source code. This makes scripts significantly more efficient than on-the-fly generated code (Anthropic Engineering Blog).

2.4. How do I organise additional files in a skill?  

Short answer: Link references a maximum of one level deep from SKILL.md, place scripts in a dedicated scripts/ subfolder, name files according to their domain.

Detailed explanation:

pdf-skill/
├── SKILL.md              # Main instructions (loaded on trigger)
├── FORMS.md              # Form guide (loaded on demand)
├── reference.md          # API reference (loaded on demand)
├── examples.md           # Usage examples (loaded on demand)
└── scripts/
  ├── analyze_form.py   # Utility script (executed, not loaded)
  ├── fill_form.py      # Form script
  └── validate.py       # Validation script

For extensive reference files (over 100 lines), Anthropic recommends a table of contents at the beginning so that Claude can grasp the scope, even if it initially only reads a section (Best Practices).

2.5. What naming conventions should I use for skills?  

Short answer: Gerund form preferred (e.g., processing-pdfs), consistent within your skill collection, no vague names like helper or utils.

Detailed explanation:

Consistent naming facilitates referencing in documentation, organising large skill libraries, and quick comprehension at a glance (Best Practices).

3.1. How do I write effective skill descriptions?  

Short answer: Always use the third person, include specific trigger terms, and cover both the what and the when in a single sentence.

Detailed explanation:

The description is the most important text in the skill – it determines whether the agent selects the skill. Anthropic recommends three rules:

1. Use the third person: "Processes Excel files and generates reports" instead of "I can help you process Excel files"
2. Include specific terms: Instead of "Helps with documents" → "Extract text and tables from PDF files, fill forms, merge documents"
3. Define trigger context: "Use when working with PDF files or when the user mentions PDFs, forms, or document extraction"

# Bad:
description: Helps with documents

# Good:
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

The official skill-creator from Anthropic adds an important style rule: Always use the imperative/infinitive form in the body of the SKILL.md. Furthermore, "When to Use" information should be placed exclusively in the description – not in the body, as the body is only loaded after the trigger occurs (skills.sh).

3.2. How do I develop skills iteratively with Claude?  

Short answer: With the two-instance method: Claude A creates the skill, Claude B tests it on real tasks, and you iterate based on observations.

Detailed explanation:

The process is based on a central insight from Anthropic: Claude models natively understand the skill format. You do not need any special system prompts to support Claude in creating skills – just ask. The key lies in observing Claude B: Where does it struggle? Which files does it not read? Which instructions does it skip? (Best Practices)

Anthropic also offers official CLI tools for the entire lifecycle: init_skill.py generates a template directory with the correct structure, and package_skill.py validates and packages the finished skill as a .skill file (a ZIP with a .skill extension) for distribution (skills.sh). In Cursor, the entire migration process can also be triggered via the integrated /migrate-to-skills command, which automatically converts existing Rules and Commands.

3.3. How do I create evaluations for my skills?  

Short answer: Create 3-5 representative test scenarios per skill that cover positive triggers, negative triggers, and edge cases – ideally before writing the skill.

Detailed explanation:

Anthropic advocates Evaluation-driven Development: evaluations first, skill content afterwards. This ensures that the skill solves real problems instead of imaginary ones (Best Practices).

{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
  "Successfully reads the PDF file using an appropriate library",
  "Extracts text content from all pages without missing any",
  "Saves the extracted text to output.txt in a clear format"
]
}

For enterprise deployments, the Enterprise Documentation recommends testing across all models used (Haiku, Sonnet, Opus), as skill effectiveness is model-dependent.

3.4. When should I use scripts instead of instructions?  

Short answer: For deterministic operations, fragile processes, and compute-intensive tasks – anywhere consistency and efficiency are more important than flexibility.

Detailed explanation:

Scripts offer four advantages over generated code solutions: reliability (tested and deterministic), token savings (no code in the context window), time savings (no code generation required), and consistency across multiple uses.

The official skill-creator describes this decision as a "Degrees of Freedom" model:

The engineering team provides sorting a list as an example: via token generation, this would be significantly more expensive than a simple sorting algorithm within a script (Engineering Blog). The Engineering Blog thereby emphasises an often overlooked advantage: scripts offer deterministic reliability beyond pure efficiency. In the concrete PDF skill example, a pre-written Python script extracts all form fields without loading either the script source code or the PDF itself into the context window – this ensures the automation remains consistent and reproducible across any number of runs.

3.5. How do I implement feedback loops in skills?  

Short answer: The "Validate → Correct → Repeat" pattern combines checklists for text-based tasks and validator scripts for code-based workflows.

Detailed explanation:

Feedback loops significantly improve output quality. Anthropic describes two variants:

Variant 1 – Without code (style guide compliance):

1. Create content according to the guidelines in STYLE_GUIDE.md
2. Check against a checklist (terminology, format, completeness)
3. In case of issues: correct and check again
4. Only finalise upon passing

Variant 2 – With code (document validation):

1. Edit the XML file
2. Validate immediately: python scripts/validate.py unpacked_dir/
3. On error: fix issues and validate again
4. Only proceed upon successful validation

4.1. How do I use Skills with the Claude API?  

Short answer: Via the container parameter in the Messages API call, along with three beta headers and the code execution tool.

Detailed explanation:

The API integration requires three beta headers:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
  model="claude-opus-4-6",
  max_tokens=4096,
  betas=["code-execution-2025-08-25", "skills-2025-10-02"],
  container={
      "skills": [{
          "type": "anthropic",
          "skill_id": "pptx",
          "version": "latest"
      }]
  },

Custom Skills are uploaded via the Skills API (/v1/skills endpoints) and are then available workspace-wide (Quickstart).

The Agent Skills Cookbook offers Jupyter Notebook tutorials for each of the four document Skills (PDF, PowerPoint, Excel, Word) – including environment setup, API client configuration, and programmatic Skill discovery. The tutorials also demonstrate how available Skills can be queried via the API and integrated into your own workflows. The Anthropic Python SDK version 0.71.0 or higher is required as a prerequisite.

4.2. How do I use skills in Claude Code and Cursor?  

Short answer: Place SKILL.md files in the respective skills directory – both tools will discover them automatically. Cursor also reads .claude/skills/ and .codex/skills/ for cross-compatibility.

Detailed explanation:

Cursor offers additional functions:

• GitHub import: Install skills directly from GitHub repositories (Cursor Settings → Rules → Add Rule → Remote Rule)
• Viewing: View installed skills under Cursor Settings → Rules → "Agent Decides"
• Migration: The built-in /migrate-to-skills command converts dynamic rules (alwaysApply: false) and slash commands into skills – rules with alwaysApply: true or specific globs patterns are intentionally not migrated

Claude Code, in turn, provides its own advanced features :

• Subagents: Skills can be executed in isolated subagents via context: fork
• Hooks: Lifecycle hooks (e.g., after a build) can trigger skills automatically
• Dynamic context: Shell commands (!git status) can be executed directly in the prompt

Additionally, Claude Code includes five bundled skills that demonstrate advanced patterns: /batch orchestrates large-scale code changes via parallel subagents in isolated Git worktrees, /simplify checks recently modified files for code quality, /debug analyses session logs, /loop repeatedly executes prompts at a set interval, and /claude-api loads API reference material for the respective project language (Claude Code Docs) . Custom commands have been merged into the skills format: A file located at .claude/commands/deploy.md and a skill located at .claude/skills/deploy/SKILL.md both generate the /deploy command and function identically.

Both tools support manual invocation via /skill-name and disabling automatic detection with disable-model-invocation: true .

4.3. How do I activate skills in Claude.ai?  

Short answer: Pre-built skills are automatically active. Custom skills can be uploaded as a ZIP file under Settings > Features – available on Pro, Max, Team, and Enterprise.

Detailed explanation:

Pre-built skills work in the background as soon as you create documents – without any setup. Custom skills require uploading a ZIP file containing the skill directory via the settings.

4.4. How do skills work in the Agent SDK?  

Short answer: Place SKILL.md files in .claude/skills/ and include "Skill" in the allowed_tools configuration – the SDK detects them automatically.

Detailed explanation:

The Claude Agent SDK supports custom skills via file system-based configuration . Skills are stored in .claude/skills/ and activated by including "Skill" in allowed_tools. Automatic detection works in the same way as Claude Code.

4.5. Can multiple skills be used simultaneously?  

Short answer: Yes, the API supports up to 8 skills per request – but too many simultaneous skills can reduce recall accuracy.

Detailed explanation:

Each skill's metadata (~100 tokens) competes for attention in the system prompt. With too many skills, Claude might miss the right skill or select irrelevant ones. The Enterprise documentation advises:

• Measure recall accuracy when adding skills
• Consolidate narrow skills into broader ones if necessary
• Route requests via role-based skill sets

5.1. What security risks do Skills pose?  

Short Answer: Skills can instruct Claude to execute code, access files, make network requests, and exfiltrate data – treat their installation like software on production systems.

Detailed Explanation:

The research group led by Xinyi Hou (Huazhong University) has shown in their MCP Landscape Analysis that external tool integrations – which also include Skill-based workflows – can open up new attack vectors, particularly with unaudited third-party Skills .

5.2. How do I review a skill before use?  

Short answer: With Anthropic's 8-point checklist: read all files, sandbox scripts, identify network access, check credentials, document tool invocations.

Detailed explanation:

The Enterprise documentation defines a detailed review checklist:

5.3. How do I manage skills within a company?  

Short answer: With a 6-phase lifecycle: Plan → Create and Review → Test → Deploy → Monitor → Iterate or Deprecate.

Detailed explanation:

Core recommendations from the enterprise documentation :

• Separation of Duties: Skill authors should not be their own reviewers
• Evaluation suites: Require at least 3-5 representative queries per skill
• Isolation and coexistence tests: Test each skill individually and together with others
• Internal registry: Document the purpose, owner, version, dependencies, and evaluation status for each skill

5.4. How do I organise skills for different teams?  

Short answer: Create role-based bundles; each team receives only the skills relevant to their daily workflows.

Detailed explanation:

The enterprise documentation recommends: Start specific, consolidate when necessary. Only merge narrow skills when evaluations confirm that the consolidated skill performs equally well (Enterprise Docs).

5.5. How do I version and distribute skills?  

Short answer: Git as the single source of truth, pinned versions in production, checksum verification during deployment, and separate uploads for each platform.

Detailed explanation:

• Production: Pin specific versions, run full evaluation suite before promotion
• Development: Use latest versions to validate changes prior to production
• Rollback plan: Keep the previous version ready as a fallback
• Integrity: Calculate checksums of verified skills and verify them during deployment

6.1. How do I handle skills with MCP tool references?  

Short answer: Always use fully qualified tool names in the ServerName:tool_name format to avoid "Tool not found" errors.

Detailed explanation:

When a skill uses MCP tools , the server prefix must be specified – especially when multiple MCP servers are available:

# Correct: Fully qualified
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

# Incorrect: Without prefix
Use the bigquery_schema tool to retrieve table schemas.

The Model Context Protocol defines the open standard for connecting AI applications with external systems. The official analogy: "Think of MCP like a USB-C port for AI applications" – a standardised connection through which AI applications access data sources, tools, and workflows . MCP is now supported by a broad ecosystem: alongside Claude, this includes ChatGPT, VS Code, Cursor, and many other clients. Anthropic views skills as a complement to MCP: while MCP provides access to tools, skills teach the agent the complex workflows surrounding these tools (Engineering Blog).

6.2. What are the token limits for skills?  

Short answer: ~100 tokens for metadata (always loaded), under 5,000 tokens for SKILL.md (when triggered), and effectively unlimited for bundled files (on-demand via Bash).

Detailed explanation:

The context window is a shared resource. Anthropic recommends the default assumption: Claude is already highly intelligent – only add context that Claude does not already have.

Three guiding questions for any information in the skill:

1. "Does Claude really need this explanation?"
2. "Can I assume that Claude already knows this?"
3. "Does this paragraph justify its token cost?"

The Best Practices illustrate the difference: A concise code example for PDF extraction requires ~50 tokens, whereas a detailed explanation with background knowledge requires ~150 tokens – three times as much for the same information content .

6.3. Why are some Skills not triggered?  

Short Answer: The most common causes are vague descriptions, too many competing Skills, or missing trigger terms in the Description.

Detailed Explanation:

The Enterprise documentation identifies five evaluation dimensions that are relevant for trigger issues:

6.4. How do I debug issues with skills?  

Short answer: Observe navigation paths, test trigger accuracy with evaluations, and distinguish between isolation and coexistence tests.

Detailed explanation:

A systematic debugging approach involves four steps:

Pay special attention to:

• Unexpected exploration paths: Is Claude reading files in an unexpected order?
• Missed connections: Is Claude failing to follow references to important files?
• Over-reliance: If Claude repeatedly reads the same file, its content should perhaps be placed in SKILL.md
• Ignored content: If a bundled file is never read, it might be unnecessary or poorly linked

6.5. Which platform differences do I need to consider?  

Short answer: Network access, package installation, sharing scope, and skill discovery vary significantly between Claude API, Claude.ai, Claude Code, and Cursor.

Detailed explanation:

The community example PleasePrompto/notebooklm-skill demonstrates how a skill for Claude Code can be created and shared via Git – a pattern that can be transferred to all file system-based platforms. In Cursor, such skills can be installed directly via GitHub import.

Summary