The Hard Truth About Agent Skills

In December 2025, Anthropic published Agent Skills as an open standard. Microsoft, Cursor, and others adopted it. There's now a specification at agentskills.io, a directory structure, YAML frontmatter requirements, and a whole ecosystem.

But before we dive into frameworks and specifications, let's understand what skills actually are.

What Anthropic Says Skills Are

From the official documentation:

Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant.

The key insight from Anthropic's engineering blog: skills are reusable, filesystem-based resources that give Claude domain-specific expertise. Instead of explaining the same thing every conversation, you write it once as a skill.

The Problem Skills Solve

Without skills:

• You re-explain procedures every session
• Context fills with repeated instructions
• No consistency across conversations

With skills:

• Write instructions once
• Load only when relevant
• Consistent behavior across sessions

That's the pitch. And it makes sense.

The Official Structure

Anthropic's specification requires a specific structure:

.claude/skills/youtube-transcribe/
├── SKILL.md              # Required
├── scripts/
│   └── transcript.sh     # Optional
└── references/
    └── api-docs.md       # Optional

The SKILL.md file needs YAML frontmatter:

---
name: youtube-transcribe
description: Transcribe YouTube videos to text. Use when user wants to extract transcript from a YouTube URL.
---

# YouTube Transcription

To transcribe a video:
1. Run: `scripts/transcript.sh "<youtube-url>"`
2. Output saves to: `transcripts/<video-id>.txt`

Progressive Disclosure

Anthropic designed skills around three loading levels:

The idea: load only what you need, when you need it. Don't dump everything into every conversation.

This is genuinely clever architecture for context management.

Now, The Hard Truth

Here's what the specification doesn't emphasize:

Skills are just text.

The YAML frontmatter? Parsed into text for the prompt. The directory structure? A convention for organization. The "progressive disclosure"? Claude reading files from disk.

Strip away the framework, and a skill is:

• A description (so Claude knows when to use it)
• Instructions (how to do the thing)
• Maybe a script (to run)

That's it.

What This Means in Practice

Consider these two approaches:

Approach A: Formal Skill

.claude/skills/youtube-transcribe/SKILL.md

---
name: youtube-transcribe
description: Transcribe YouTube videos to text files
---

# YouTube Transcription
Run: bun scripts/youtube-transcript.sh "<url>"

Approach B: Simple Guide

guides/how-to-transcribe-youtube.md

# How to Transcribe YouTube Videos
Run: bun scripts/youtube-transcript.sh "<url>"

To Claude, these are nearly identical. Both are text files with instructions. Both can be found by searching. Both tell Claude what to do.

The difference:

• Approach A: Frontmatter gets pre-loaded at startup (~100 tokens)
• Approach B: Claude searches when it needs the information

Is pre-loading the description worth the structure overhead? Sometimes yes, sometimes no.

When the Structure Helps

The Anthropic structure genuinely helps when:

You have many skills and need discoverability

If you have 50 capabilities, pre-loading descriptions lets Claude know they exist without reading all 50 files. The metadata acts as an index.

You want slash-command invocation

Skills become /youtube-transcribe commands. Users can invoke them directly. That's a real UX benefit.

You need tool restrictions

The allowed-tools field restricts what a skill can do. Security benefit for sensitive operations.

You're distributing skills to others

The open standard means skills work across Claude Code, Cursor, VS Code. Portability matters.

When Simple Guides Win

But often, simple markdown guides work just as well:

One-off procedures

# Deploy to Production
1. Run tests: `bun test`
2. Build: `bun run build`
3. Deploy: `./deploy.sh production`

Does this need to be a formal skill? Probably not. It's a guide. Claude finds it when relevant.

Project-specific knowledge

# Our Brand Voice
- Professional but approachable
- No jargon unless explained
- Examples over abstractions

This is context, not a capability. A markdown file in docs/ is fine.

Quick references

# API Credentials
- Google Analytics: Property 478766521
- Mailgun: Check .env for MAILGUN_API_KEY
- Sentry: Project teamday-cc

Index information. Doesn't need progressive disclosure.

The Spectrum

Skills exist on a spectrum from trivial to comprehensive:

One-Liners (maybe don't need formal skills)

Email notifications: bun scripts/mailgun.send.js --to="x" --subject="y"

Quick References (borderline)

# Google Analytics
Use the mcp__google-analytics tools.
Property ID: 478766521
Common queries: pageviews, sessions, top pages

Step-by-Step Guides (formal skill makes sense)

# Add YouTube Video to Newsfeed

1. Fetch transcript
2. Extract metadata with curl (not WebFetch!)
3. Create feed post
4. Update embeddings
5. Extract entities
6. Trigger translations

Comprehensive Workflows (definitely a skill)

Multi-step procedures with scripts, validation, error handling. The newsfeed skill we use is 250+ lines with sub-documents for specific tasks.

The more complex the capability, the more the formal structure pays off.

The Filesystem Is Your Friend

Here's what the Anthropic engineering blog emphasizes that often gets overlooked:

Claude has filesystem access. Scripts execute via bash. Reference files exist on disk. You can bundle effectively unlimited reference materials.

Claude can:

• Search for files: grep -r "transcribe" docs/
• Read what it finds: Read: docs/how-to-transcribe.md
• Execute scripts: bash scripts/transcribe.sh

Progressive discovery doesn't require the skill framework. It requires good file organization and an AI that knows how to search.

The skill framework formalizes this with metadata. But the underlying mechanism is just filesystem navigation.

Context Is Everything

The real insight from Anthropic's design: context windows are limited.

Claude Code's system prompt is reportedly 72kb. That's ~18,000 tokens before you even start working. Every skill description adds to this.

The progressive disclosure design addresses this:

• Metadata only at startup (small)
• Full instructions when triggered (medium)
• Scripts/references when needed (unlimited, not in context)

But you get the same benefit from:

• Minimal system prompt
• Claude searches docs when needed
• Reads only what's relevant

The principle matters more than the implementation.

What Actually Matters

After building dozens of AI workflows, here's what we've learned:

1. Clear Instructions Beat Clever Structure

# Generate Blog Cover

We use FAL AI. Images save to public/images/.

Run:
bun scripts/generate-image.ts "prompt" name.webp

Good prompts:
- Include style ("minimalist illustration")
- Include subject ("AI agents collaborating")
- Include mood ("professional, tech-forward")

Claude follows this whether it's a formal skill or a doc file.

2. Discoverability Is Real

If Claude can't find your instructions, structure doesn't matter. Whether through skill descriptions or good filenames, make things findable.

• ✅ guides/how-to-transcribe-youtube.md
• ✅ Skill with clear description
• ❌ notes/misc/stuff-v2-final.md

3. Scripts Solve Complexity

When instructions get complex, write a script:

# Instead of 20 lines of instructions:
bun scripts/add-video-to-newsfeed.ts "<youtube-url>"

The script encapsulates complexity. The skill just documents how to invoke it.

4. Iterate Based on Failures

When Claude does something wrong:

• Unclear instruction? → Improve the text
• Missing information? → Add it
• Can't find it? → Better naming or add to skill index

Don't add defensive rules. Fix the actual problem.

The Takeaway

Anthropic built a thoughtful system for organizing AI capabilities. Progressive disclosure is clever. The open standard enables portability. Slash commands improve UX.

But here's the hard truth:

Skills are just text instructions that Claude reads from files.

The framework adds:

• Pre-loaded descriptions (index)
• Slash-command invocation
• Tool restrictions
• Cross-platform portability

These are real benefits for complex setups with many capabilities.

But for everyday work:

• A well-named markdown file works
• Claude can search and find things
• Clear instructions matter more than structure
• The filesystem is already a discovery system

Don't over-engineer. Start with simple guides. Add formal skill structure when the benefits justify the overhead.

Write clearly. Organize sensibly. Let Claude do its job.

We use both approaches at TeamDay. Formal skills for complex workflows like newsfeed management. Simple guides for one-off procedures. The key is matching the tool to the task.