Skip to content

Instantly share code, notes, and snippets.

@rafaelcalleja

rafaelcalleja/00-skills-explained-main-article.md

Created December 28, 2025 05:16
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save rafaelcalleja/aa4f8263164716826907085e0c9173a5 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save rafaelcalleja/aa4f8263164716826907085e0c9173a5 to your computer and use it in GitHub Desktop.
Download ZIP
Skills explained: How Skills compares to prompts, Projects, MCP, and subagents
Raw
00-skills-explained-main-article.md

Skills explained: How Skills compares to prompts, Projects, MCP, and subagents

Skills are an increasingly powerful tool for creating custom AI workflows and agents, but where do they fit in the Claude stack? We explain what tool to use when - and how they all work together.

Date: November 13, 2025 | Reading time: 5 min | Category: Agents

Since introducing Skills, there's been interest in understanding how the various components of Claude's agentic ecosystem work together.

Whether you're building sophisticated workflows in Claude Code, creating enterprise solutions with the API, or maximizing your productivity on Claude.ai, knowing which tool to reach forand whencan transform how you work with Claude.

This guide breaks down each building block, explains when to use what, and shows you how to combine them for powerful agentic workflows.

Understanding your agentic building blocks

What are Skills?

Skills are folders containing instructions, scripts, and resources that Claude discovers and loads dynamically when relevant to a task. Think of them as specialized training manuals that give Claude expertise in specific domainsfrom working with Excel spreadsheets to following your organization's brand guidelines.

How Skills work: When Claude encounters a task, it scans available Skills to find relevant matches. Skills use progressive disclosure: metadata loads first (~100 tokens), providing just enough information for Claude to know when a Skill is relevant. Full instructions load when needed (<5k tokens), and bundled files or scripts load only as required.

When to use Skills: Choose Skills when you need Claude to perform specialized tasks consistently and efficiently. They're ideal for:

  • Organizational workflows: Brand guidelines, compliance procedures, document templates
    • Domain expertise: Excel formulas, PDF manipulation, data analysis
    • Personal preferences: Note-taking systems, coding patterns, research methods

Example: Create a brand guidelines Skill that includes your company's color palette, typography rules, and layout specifications. When Claude creates presentations or documents, it automatically applies these standards without you needing to explain them each time.

Learn more about Skills and check out our growing Skills library.

What are prompts?

Prompts are the instructions you provide to Claude in natural language during a conversation. They're ephemeral, conversational, and reactiveyou provide context and direction in the moment.

When to use prompts: Use prompts for:

  • One-off requests: "Summarize this article"
    • Conversational refinement: "Make that tone more professional"
    • Immediate context: "Analyze this data and identify trends"
    • Ad-hoc instructions: "Format this as a bulleted list"

Pro-tip: Prompts are your primary way of interacting with Claude, but they don't persist across conversations. For repeated workflows or specialized knowledge, consider capturing prompts as Skills or project instructions.

Check out our prompt library, prompting best practices, or our smart prompt maker to get started.

What are Projects?

Available on all paid Claude plans, Projects are self-contained workspaces with their own chat histories and knowledge bases. Each project includes a 200K context window where you can upload documents, provide context, and set custom instructions that apply to all conversations within that project.

How Projects work: Everything you upload to a project's knowledge base becomes available across all chats within that project. Claude automatically uses this context to provide more informed, relevant responses.

When to use Projects: Choose Projects when you need:

  • Persistent context: Background knowledge that should inform every conversation
    • Workspace organization: Separate contexts for different initiatives
    • Team collaboration: Shared knowledge and conversation history (on Team and Enterprise plans)
    • Custom instructions: Project-specific tone, perspective, or approach

What are subagents?

Subagents are specialized AI assistants with their own context windows, custom system prompts, and specific tool permissions. Available in Claude Code and the Claude Agent SDK, subagents handle discrete tasks independently and return results to the main agent.

When to use subagents: Use subagents for:

  • Task specialization: Code review, test generation, security audits
    • Context management: Keep the main conversation focused while offloading specialized work
    • Parallel processing: Multiple subagents can work on different aspects simultaneously
    • Tool restriction: Limit specific subagents to safe operations (e.g., read-only access)

Learn more about subagents.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external systems where data livescontent repositories, business tools, databases, and development environments.

How MCP works: MCP provides a standardized way to connect Claude to your tools and data sources. Instead of building custom integrations for each data source, you build against a single protocol. MCP servers expose data and capabilities; MCP clients (like Claude) connect to these servers.

When to use MCP: Choose MCP when you need Claude to:

  • Access external data: Google Drive, Slack, GitHub, databases
    • Use business tools: CRM systems, project management platforms
    • Connect to development environments: Local files, IDEs, version control
    • Integrate with custom systems: Your proprietary tools and data sources

Learn more about MCP and check out documentation on how to build an MCP server.

How they work together

The real power emerges when you combine these building blocks. Each serves a distinct purpose, and together they create sophisticated agentic workflows.

Feature Skills Prompts Projects Subagents MCP
What it provides Procedural knowledge Moment-to-moment instructions Background knowledge Task delegation Tool connectivity
Persistence Across conversations Single conversation Within project Across sessions Continuous connection
Contains Instructions + code + assets Natural language Documents + context Full agent logic Tool definitions
When it loads Dynamically, as needed Each turn Always in project When invoked Always available
Can include code Yes No No Yes Yes
Best for Specialized expertise Quick requests Centralized context Specialized tasks Data access

Getting started

Ready to build with Skills? Here's how to start:

Claude.ai users:

  • Enable Skills in Settings Features
    • Create your first project at claude.ai/projects
    • Try combining project knowledge with Skills for your next analysis task

API developers:

Claude Code users:

Related Resources

Source: https://claude.com/blog/skills-explained

Raw
01-introducing-agent-skills.md

Introducing Agent Skills

Claude can now use Skills to improve how it performs specific tasks. Skills are folders that include instructions, scripts, and resources that Claude can load when needed.

Date: October 16, 2025 | Reading time: 5 min | Category: Product announcements

Update: We've added organization-wide management for skills, a directory featuring partner-built skills, and published Agent Skills as an open standard for cross-platform portability. (December 18, 2025)

Claude can now use Skills to improve how it performs specific tasks. Skills are folders that include instructions, scripts, and resources that Claude can load when needed.

Claude will only access a skill when it's relevant to the task at hand. When used, skills make Claude better at specialized tasks like working with Excel or following your organization's brand guidelines.

You've already seen Skills at work in Claude apps, where Claude uses them to create files like spreadsheets and presentations. Now, you can build your own skills and use them across Claude apps, Claude Code, and our API.

How Skills work

While working on tasks, Claude scans available skills to find relevant matches. When one matches, it loads only the minimal information and files neededkeeping Claude fast while accessing specialized expertise.

Skills are:

  • Composable: Skills stack together. Claude automatically identifies which skills are needed and coordinates their use.
    • Portable: Skills use the same format everywhere. Build once, use across Claude apps, Claude Code, and API.
    • Efficient: Only loads what's needed, when it's needed.
    • Powerful: Skills can include executable code for tasks where traditional programming is more reliable than token generation.

Think of Skills as custom onboarding materials that let you package expertise, making Claude a specialist on what matters most to you.

Skills work with every Claude product

Claude apps

Skills are available to Pro, Max, Team and Enterprise users. We provide skills for common tasks like document creation, examples you can customize, and the ability to create your own custom skills.

Claude automatically invokes relevant skills based on your taskno manual selection needed. You'll even see skills in Claude's chain of thought as it works.

Creating skills is simple. The "skill-creator" skill provides interactive guidance: Claude asks about your workflow, generates the folder structure, formats the SKILL.md file, and bundles the resources you need.

Enable Skills in Settings. For Team and Enterprise users, admins must first enable Skills organization-wide.

Claude Developer Platform (API)

Agent Skills can now be added to Messages API requests and the new /v1/skills endpoint gives developers programmatic control over custom skill versioning and management. Skills require the Code Execution Tool beta, which provides the secure environment they need to run.

Use Anthropic-created skills to have Claude read and generate professional Excel spreadsheets with formulas, PowerPoint presentations, Word documents, and fillable PDFs.

Claude Code

Skills extend Claude Code with your team's expertise and workflows. Install skills via plugins from the anthropics/skills marketplace. Claude loads them automatically when relevant. Share skills through version control with your team.

Getting started

  • Claude apps: User Guide & Help Center
    • API developers: Documentation
    • Claude Code: Documentation
    • Example Skills to customize: GitHub repository

What's next

We're working toward simplified skill creation workflows and enterprise-wide deployment capabilities, making it easier for organizations to distribute skills across teams.

Keep in mind, this feature gives Claude access to execute code. While powerful, it means being mindful about which skills you usestick to trusted sources to keep your data safe.

Source: https://claude.com/blog/skills

Raw
02-introducing-model-context-protocol.md

Introducing the Model Context Protocol

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to the systems where data lives, including content repositories, business tools, and development environments.

Date: November 25, 2024 | Category: Announcements

Today, we're open-sourcing the Model Context Protocol (MCP), a new standard for connecting AI assistants to the systems where data lives, including content repositories, business tools, and development environments. Its aim is to help frontier models produce better, more relevant responses.

As AI assistants gain mainstream adoption, the industry has invested heavily in model capabilities, achieving rapid advances in reasoning and quality. Yet even the most sophisticated models are constrained by their isolation from datatrapped behind information silos and legacy systems. Every new data source requires its own custom implementation, making truly connected systems difficult to scale.

MCP addresses this challenge. It provides a universal, open standard for connecting AI systems with data sources, replacing fragmented integrations with a single protocol. The result is a simpler, more reliable way to give AI systems access to the data they need.

Model Context Protocol

The Model Context Protocol is an open standard that enables developers to build secure, two-way connections between their data sources and AI-powered tools. The architecture is straightforward: developers can either expose their data through MCP servers or build AI applications (MCP clients) that connect to these servers.

Three major components:

  1. The Model Context Protocol specification and SDKs
    1. Local MCP server support in the Claude Desktop apps
    1. An open-source repository of MCP servers

Claude 3.5 Sonnet is adept at quickly building MCP server implementations, making it easy for organizations and individuals to rapidly connect their most important datasets with a range of AI-powered tools.

Pre-built MCP servers available for:

  • Google Drive
    • Slack
    • GitHub
    • Git
    • Postgres
    • Puppeteer

Early Adopters

Early adopters like Block and Apollo have integrated MCP into their systems, while development tools companies including Zed, Replit, Codeium, and Sourcegraph are working with MCP to enhance their platforms.

"At Block, open source is more than a development modelit's the foundation of our work and a commitment to creating technology that drives meaningful change and serves as a public good for all." Dhanji R. Prasanna, CTO at Block

Getting started

Developers can start building and testing MCP connectors today. All Claude.ai plans support connecting MCP servers to the Claude Desktop app.

  • Install pre-built MCP servers through the Claude Desktop app
    • Follow our quickstart guide to build your first MCP server
    • Contribute to our open-source repositories of connectors and implementations

An open community

We're committed to building MCP as a collaborative, open-source project and ecosystem, and we're eager to hear your feedback. Whether you're an AI tool developer, an enterprise looking to leverage existing data, or an early adopter exploring the frontier, we invite you to build the future of context-aware AI together.

Source: https://www.anthropic.com/news/model-context-protocol

Raw
03-equipping-agents-with-skills-engineering.md

Equipping Agents for the Real World with Agent Skills

Technical deep-dive on the Agent Skills design pattern, architecture, and development best practices.

Category: Engineering Blog | Authors: Barry Zhang, Keith Lazuka, Mahesh Murag

As model capabilities improve, we can now build general-purpose agents that interact with full-fledged computing environments. Claude Code, for example, can accomplish complex tasks across domains using local code execution and filesystems. But as these agents become more powerful, we need more composable, scalable, and portable ways to equip them with domain-specific expertise.

This led us to create Agent Skills: organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.

What is a Skill?

A skill is a directory containing a SKILL.md file that contains organized folders of instructions, scripts, and resources that give agents additional capabilities. Building a skill for an agent is like putting together an onboarding guide for a new hire.

The anatomy of a skill

At its simplest, a skill is a directory that contains a SKILL.md file. This file must start with YAML frontmatter containing:

  • name: The skill's identifier
    • description: What the skill does

At startup, the agent pre-loads the name and description of every installed skill into its system prompt.

Progressive Disclosure

Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable. Like a well-organized manual, skills let Claude load information only as needed:

Three Levels of Detail:

  1. Metadata (First Level): Name and description loaded at startup (~100 tokens) - just enough for Claude to know when each skill should be used
    1. Full SKILL.md (Second Level): Loaded when Claude thinks the skill is relevant to the current task
    1. Additional Files (Third Level): Referenced files that Claude can navigate and discover only as needed

This means the amount of context that can be bundled into a skill is effectively unbounded.

Skills and Code Execution

Skills can include code for Claude to execute as tools at its discretion.

Large language models excel at many tasks, but certain operations are better suited for traditional code execution. For example:

  • Sorting via token generation is far more expensive than running a sorting algorithm
    • Many applications require the deterministic reliability that only code can provide

Developing and Evaluating Skills

Best Practices:

  1. Start with evaluation: Identify specific gaps by running agents on representative tasks
    1. Structure for scale: Split content into separate files when SKILL.md becomes unwieldy
    1. Think from Claude's perspective: Pay attention to name and description - Claude uses these to decide whether to trigger the skill
    1. Iterate with Claude: Ask Claude to capture successful approaches and common mistakes into reusable context

Security Considerations

Skills provide Claude with new capabilities through instructions and code. Recommendations:

  • Install skills only from trusted sources
    • Thoroughly audit skills from less-trusted sources
    • Pay attention to code dependencies and bundled resources
    • Watch for instructions connecting to untrusted external network sources

The Future of Skills

Agent Skills are supported across:

  • Claude.ai
    • Claude Code
    • Claude Agent SDK
    • Claude Developer Platform

Looking ahead, we hope to enable agents to create, edit, and evaluate Skills on their own, letting them codify their own patterns of behavior into reusable capabilities.

Source: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

Raw
04-what-is-model-context-protocol.md

What is Model Context Protocol? Connect AI to your world

Connect AI assistants to your tools without custom integrations using Model Context Protocol.

Date: October 31, 2025 | Reading time: 5 min | Category: Agents

AI models are only as good as the context provided to them. AI assistants like Claude can answer questions and perform an impressive range of tasks, but if they can't access the data or tools they need, they're limited in what they can do for you.

What is the Model Context Protocol (MCP)?

The Model Context Protocol is an open standard that defines how LLMs communicate with external systems.

Think of MCP as USB-C for LLMs. Just as USB-C provides a universal connector for your phone, laptop, and other devices, MCP provides a universal format for LLMs to connect with external systems.

Where did MCP come from?

MCP was created at Anthropic by David Sorria Para and Justin Spahr-Summers. The idea originated from David's frustration with constantly copying code between Claude Desktop and his IDE. They designed MCP based on the popular Language Server Protocol and open-sourced it in November 2024.

How does MCP work?

MCP works through a two-sided approach:

  • MCP Clients: AI agents and chatbots like Claude create these to connect to applications
    • MCP Servers: Companies like Notion, Canva, or Figma make their tools and data available through these

Why is MCP important?

Universal compatibility for AI

  • AI assistants gain access to thousands of tools
    • Tools and applications connect to every AI assistant at once

An Open, AI-native ecosystem

  • Anyone can build and share
    • Makes software AI-accessible by design

A foundational protocol for agents

MCP creates the infrastructure for AI agents to access any number of services and tools, enabling true end-to-end task automation.

Who is MCP for?

  • Developers: Get a standardized way to build integrations once
    • Enterprises: Gain secure, IT-controlled AI connectivity that scales
    • Consumers: Connect favorite tools to AI instantly, with no technical knowledge required

Connectors (MCP) in action

Available Claude Connectors include:

  • Notion for workspace documentation
    • Linear for issue tracking
    • Stripe for payment data
    • Canva and Figma for design assistance
    • HubSpot for automating CRM tasks
    • Sentry for error tracking
    • ...and many more

FAQ

Is MCP only for Claude? No. MCP is an open-source protocol. Other AI providers have now adopted the same protocol.

Do I need programming skills to use MCP? Not for using connectors. Browse, install, authenticate. That's it.

How does security work for MCP? Each server requests specific permissions. You can approve or deny access and revoke permissions at any time.

Source: https://claude.com/blog/what-is-model-context-protocol

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment