![[claude_skills.png]] ## Introduction Imagine if you could teach Claude (Anthropic's AI assistant) how to perform specialised tasks the way you'd train a new team member. Instead of starting from scratch each time you need something done, you could package your expertise, workflows, and best practices into reusable resources that Claude automatically recognises and applies when relevant. That's the promise of Claude Skills. Skills are **organised folders** containing **instructions, scripts, and reference materials** that Claude discovers and loads dynamically when they're needed for a task. Rather than building separate custom agents[^1] for different use cases, you can equip one Claude agent with multiple specialised capabilities. In this article, we'll explore what Skills are, how they work, why they matter, and how you can create and use them effectively. ## What Are Claude Skills? At their core, Claude Skills are specialised knowledge packages. Each Skill is a directory containing several key components: - **SKILL.md file** - The heart of any Skill, containing instructions and guidance that Claude follows. A barebones file in the least has a brief name and description that helps Claude discover when to use the Skill - **Supporting files** - Additional markdown documents, scripts, templates, or reference materials Think of a Skill like an onboarding guide for a new team member. Just as you'd give a new hire a handbook with procedures, templates, and reference materials, a Skill bundles everything Claude needs to excel at a specific task. ### Automatic loading The key innovation here is *automatic loading*. Claude doesn't require you to manually select which Skill to use. Instead, Claude reads each Skill's description and intelligently determines[^2] which ones are relevant for your request. If you ask Claude to "extract text from a PDF," it automatically loads the PDF processing Skill. If you ask it to "create a PowerPoint presentation," it loads the presentation Skill. This happens invisibly: you just make your request, and Claude handles the rest. ## Why Skills Matter: The Problem They Solve Before Skills existed, users faced a fundamental challenge: **repetition**. If you wanted Claude to follow your organisation's brand guidelines, you'd need to paste those guidelines into the chat every single time. If you wanted Claude to use specific Excel formulas or PDF processing techniques, you'd have to re-explain them repeatedly. This approach doesn't scale. It wastes tokens, clutters conversations, and forces you to remember to include context that should be permanent. Skills solve this by creating a **central repository of expertise**. You define a workflow once, package it as a Skill, and then use it. More fundamentally, Skills transform Claude from a general-purpose assistant into a specialised agent tailored to your needs. Instead of a single Claude that tries to handle everything adequately, you can build a Claude that's **expert at your specific domain, organisation, or use case**. Also, what has been mentioned above only covers the aspect of using Claude as an individual. Imagine a scenario where Skills scale with a company and you share Claude skills amongst team members. That would ensure a team's standards / best practices are enforced automatically without having to micro-manage or police members (both agentic and human). Currently, this organisation-wide sharing does not exist as noted in the limitations section. Personally, I am a huge fan of the idea of **having actual code files (like Python scripts) for some repeatable processes**. This is **deterministic code**, almost always never requires any "context". However, I also see it as a double edged sword as having scripts with external dependencies might add some additional overhead. ## How Skills Work: The Three-Layer Architecture Understanding how Skills work means grasping three key concepts - progressive disclosure, three types of content, and the filesystem-based architecture. ### Progressive Disclosure: Loading Information in Stages The central design principle behind Skills is *progressive disclosure*. Rather than loading entire Skill instructions into Claude's context window immediately, information loads in stages as needed: **Level 1: Metadata** - Always loaded at startup. This is just the Skill's name and brief description (roughly 100 tokens per Skill). Since Claude loads all Skill metadata at startup, you can install dozens of Skills without paying a context penalty for unused instructions. Claude knows each Skill exists and what it's for, but doesn't load the full instructions for any of them until needed. **Level 2: Instructions** - Loaded when triggered. When your task matches a Skill's description, Claude reads the full SKILL.md file from the filesystem. This might contain workflows, step-by-step procedures, and guidance. Only then does this content enter Claude's context window, typically consuming under 5,000 tokens per Skill[^3]. **Level 3: Resources and code** - Loaded as needed. Skills can bundle additional files like specialised guides (`FORMS.md`, `REFERENCE.md`), executable scripts (`validate.py`, `processor.py`), templates, or reference materials. Claude accesses these files only when referenced, meaning they consume zero tokens if not needed. This layered approach is what makes Skills efficient. A PDF processing Skill might include comprehensive API documentation, form-filling guides, and dozens of example scripts. But if your task only needs basic text extraction, Claude loads just the core instructions. The other resources remain on the filesystem consuming no tokens. >[!warning] >In spite of what Anthropic has put forth, I do not think Skills are inherently efficient when it comes to context. Of course, the layered approach to deciding how much to take into context is a good feature. However, we are still at the risk of inefficiently eating into the context window if we do not "engineer" our skills efficiently. The name and description need to be clear and governed. The additional files if created need to be error free and if possible, not have external dependencies which make their operation tedious. As skills scale, the distinction between skills should be clear to avoid the risk of the agent getting confused. Also, it becomes important to have a method to the creation of skills. A skill should do only one major thing, else there is another risk of forcing the agent to do too much at once. ### Where Skills Live: The Filesystem Model Skills exist as directories in Claude's execution environment: a virtual machine where Claude has filesystem access, can run bash commands, and can execute code. When Claude needs to use a Skill, it navigates the filesystem like you would, reading specific files and running specific scripts. Here's what that looks like in practice: ``` pdf-skill/ ├── SKILL.md (main instructions) ├── FORMS.md (form-filling guide) ├── scripts/ │ └── fill_form.py (utility script) └── templates/ └── sample_form.pdf ``` When you ask Claude to "fill out this PDF form," Claude reads SKILL.md, sees it mentions form filling, then reads `FORMS.md`, then runs `fill_form.py` to complete the task. Each file loads into context only when referenced. ### How Claude Accesses Skill Content The sequence is linear. 1. **Startup**: Claude's system prompt includes metadata for all installed Skills (name and description only) 2. **User request**: You ask Claude to do something that matches a Skill's description 3. **Skill triggered**: Claude uses bash to read `SKILL.md` from the filesystem, bringing instructions into context 4. **Optional loading**: If those instructions reference other files, Claude reads them too using additional bash commands 5. **Script execution**: If instructions mention executable scripts (like `validate.py`), Claude runs them via bash. The script code itself never enters context, only the output This architecture creates several powerful properties: - **On-demand file access**: A Skill can bundle dozens of reference files. Claude loads only what each task needs - **Efficient script execution**: When Claude runs a script, only the output consumes tokens, not the script code itself - **No practical limit on bundled content**: Because files don't consume context until accessed, Skills can include comprehensive reference materials, large datasets, or extensive examples ## What Skills Can Do: Pre-Built Capabilities and Custom Extensions Anthropic provides several pre-built Skills ready to use immediately: - **Excel (xlsx)** - Create and manipulate spreadsheets with formulas, charts, and formatting - **PowerPoint (pptx)** - Generate professional presentations with slides and transitions - **Word (docx)** - Create richly formatted documents with structure and styling - **PDF (pdf)** - Generate formatted PDF documents with text, tables, and images These pre-built Skills work automatically on Claude.ai and via the Claude API. You don't need to set anything up. Claude uses them when relevant. Beyond pre-built Skills, you can create custom Skills to package organisational knowledge, procedural expertise, and domain-specific workflows. Common use cases include: - **Brand guidelines** - Package your organisation's design standards, voice, and formatting rules so Claude consistently applies them - **Financial modelling** - Create Skills that implement your company's specific calculation methodologies and reporting frameworks - **Data processing** - Bundle custom data processing workflows, validation rules, and transformation scripts - **Code generation** - Teach Claude your organisation's coding patterns, architecture standards, and testing requirements - **Content creation** - Encode your editorial guidelines, brand voice, and formatting preferences The flexibility is significant. If there's a repetitive task your team performs regularly, you can turn it into a Skill and have Claude handle it automatically. ## Where to Use Skills: Across Claude's Products Skills work consistently across Claude's ecosystem, though with different setup requirements: **Claude.ai** - Pre-built Skills are already available to users on Pro, Max, Team, and Enterprise plans. Custom Skills can be uploaded as zip files through Settings > Features (Pro+ plans with code execution enabled). However, custom Skills uploaded to Claude.ai are individual to each user and aren't shared organisation-wide. **Claude API** - Both pre-built and custom Skills are supported. Pre-built Skills (like xlsx, pptx) work by referencing their skill_id. Custom Skills can be uploaded via the Skills API and are shared across your organisation. The API requires three beta headers to enable Skills functionality. **Claude Code** - The command-line development tool supports custom Skills stored in `.claude/skills/` directories. These are filesystem-based and discovered automatically. This is ideal for developers building specialised agents in a local development environment. **Claude Agent SDK** - The Claude Agent SDK is a TypeScript/Python development framework for building custom agents. It supports custom Skills through filesystem-based configuration in `.claude/skills/`. Enable Skills in your allowed_tools configuration and they'll be discovered automatically. ## Getting Started: Creating and Using Skills ### Using Pre-Built Skills If you just want to use Anthropic's pre-built Skills, you don't need to do anything on Claude.ai. They're already available. For the Claude API, you'll need to specify the skill_id in your request. >[!warning] >Code written by AI. Not tested. ```python from anthropic import Anthropic client = Anthropic( api_key="your-api-key", default_headers={ "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14,skills-2025-10-02" } ) # Create an Excel spreadsheet response = client.messages.create( model="claude-opus-4-1-20250805", max_tokens=4096, container={ "skills": [ {"type": "anthropic", "skill_id": "xlsx", "version": "latest"} ] }, tools=[{"type": "code_execution_20250825", "name": "code_execution"}], messages=[{ "role": "user", "content": "Create a budget spreadsheet with revenue and expense categories" }] ) ``` ### Creating Custom Skills Every custom Skill requires at minimum a `SKILL.md` file with YAML frontmatter. ```yaml --- name: budget-analyzer description: Analyse budget spreadsheets, calculate variances, and generate financial reports. Use when working with budget data or financial analysis. --- # Budget Analyzer ## Quick Start [Step-by-step instructions for Claude to follow] ## Examples [Concrete examples showing how to use this Skill] ``` The frontmatter metadata is critical. It's what Claude reads at startup and uses to determine when your Skill is relevant. A good description answers two questions: what does this Skill do, and when should Claude use it? Beyond `SKILL.md`, you can add supporting files for complex Skills: ``` budget-analyzer/ ├── SKILL.md (main instructions) ├── FORMULAS.md (reference guide for financial calculations) ├── EXAMPLES.md (additional detailed examples) └── scripts/ └── validate_budget.py (validation script) ``` ## Important Limitations and Considerations While Skills are powerful, understanding their constraints helps you plan effectively: **Cross-surface fragmentation** - Custom Skills don't automatically sync across Claude's surfaces. If you upload a Skill to Claude.ai, it won't appear in the API. If you create a Skill in Claude Code, it's separate from Claude.ai. You need to manage and upload Skills separately for each surface. **Sharing scope differences** - Claude.ai Skills are individual to each user; Claude API Skills are workspace-wide; Claude Code Skills are personal or project-based. There's currently no centralised admin management for organisation-wide Skill distribution on Claude.ai. **Runtime environment constraints** - Different surfaces offer different capabilities. Claude.ai may have variable network access depending on user/admin settings. The Claude API offers no network access for Skills (they can't call external APIs). Claude Code has full network access. Plan your Skills accordingly. **Security considerations** - Only use Skills from trusted sources: those you created or those from Anthropic. Because Skills can direct Claude to execute code and invoke tools, a malicious Skill could lead to data leaks or unauthorised system access. Always audit Skills from untrusted sources before use. ## Conclusion Claude Skills represent a fundamental shift in how you work with AI. Instead of repeatedly explaining the same procedures, you can package your expertise once and reuse it everywhere. Instead of building separate AI agents for different tasks, you can equip one Claude with multiple specialised capabilities that load automatically when needed. The architecture with its three-layer progressive disclosure model means you can create comprehensive Skills without worrying about context overhead. Bundle extensive reference materials, executable code, and templates. Claude loads exactly what each task requires. Whether you're using Anthropic's pre-built Skills to generate Excel spreadsheets and PDF documents, or creating custom Skills to encode your organisation's workflows and expertise, the fundamental benefit is the same: you teach Claude once, and it applies that knowledge consistently, automatically, and efficiently across every conversation and every Claude product. ## References Here are the source links if you would like some self analysis on this. 1. [Claude Skills YouTube Overview](https://www.youtube.com/watch?v=CEvIs9y1uog) 2. [Claude Blog: Skills](https://claude.com/blog/skills) 3. [Anthropic Engineering: Equipping Agents for the Real World with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) 4. [Claude Platform Docs: Agent Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) 5. [Claude Cookbooks: Skills Examples](https://github.com/anthropics/claude-cookbooks/tree/main/skills) 6. [Anthropic Skills Repository](https://github.com/anthropics/skills) ## Further Reads 1. [Claude Skills are awesome, maybe a bigger deal than MCP](https://simonwillison.net/2025/Oct/16/claude-skills/) 2. [Awesome Claude Skills - Github Repository](https://github.com/ComposioHQ/awesome-claude-skills) [^1]: In this case, "agent" refers to the .md files we write up as commands or instructions (CLAUDE.md) for the claude code agent to use when performing a task. [^2]: This is still "non-deterministic" if you are wondering. However, the "trust" is in the idea that Claude will be able to select the most relevant skill based on the skill name and description in the `SKILL.md` file. [^3]: This is obviously an estimate from Anthropic. But what I get from this is that Anthropic is setting up some guidelines on how "large" a SKILL's content can be. Too many words / code to perform a skill and probably the results are not going to be great.