Extending Claude with Skills

In the previous lesson, you learned how to use CLAUDE.md files to give your agent persistent knowledge and consistent behavior through natural language instructions. Your travel planner agent could follow guidelines, ask clarifying questions, and structure its responses according to your specifications. But what happens when you need Claude to perform tasks that require more than just instructions? What if you need executable code, specialized utilities, or domain-specific algorithms that go beyond what natural language prompts can provide? This is where Agent Skills come in — modular, task-specific packages that extend Claude's capabilities by combining structured instructions with executable code and supporting resources. In this lesson, you'll learn how to configure the Agent SDK so Claude can discover and use Skills, and craft prompts that trigger them automatically.

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

Skills are reusable, filesystem-based resources that provide Claude with domain-specific expertise: workflows, context, and best practices. Unlike CLAUDE.md files (which provide project-wide instructions that load at startup), Skills load on-demand and can be reused across multiple projects. What makes Skills powerful is their composability — Claude can identify when a Skill is relevant and invoke it automatically, combining multiple Skills if needed for complex workflows.

The Agent SDK supports custom Skills — Skills you create yourself and place in your project's .claude/skills/ directory. Each Skill can contain three types of content that load at different times:

• Instructions: Natural language guidance in SKILL.md (and optional additional Markdown files) that describe workflows and best practices
• Code: Executable scripts that provide deterministic operations without consuming context tokens
• Resources: Reference materials like templates, documentation, schemas, or examples

This differs from CLAUDE.md files in two key ways: Skills include executable code and supporting resources beyond just instructions, and Skills use progressive disclosure (loading only when needed) rather than loading all content at startup.

Before we dive into the structure of Skills, it's helpful to know where to find examples. Anthropic maintains a public repository for Skills on GitHub with demonstrations ranging from creative applications to technical tasks to enterprise workflows.

The repository includes example Skills (many open source under Apache 2.0), the document creation Skills that power Claude's PowerPoint/Excel/Word/PDF capabilities (source-available as reference), a Skills specification, and a starter template.

The slack-gif-creator Skill we're using in this lesson follows patterns similar to those in the public repository. Now let's examine the filesystem structure that makes Skills work.

Skills live in a .claude/skills/ directory within your project, following a specific filesystem structure that the SDK recognizes automatically. Each Skill is its own subdirectory containing at minimum a SKILL.md file, with optional scripts and resource folders.

Let's examine the structure of the slack-gif-creator Skill:

.claude/
└── skills/
    └── slack-gif-creator/
        ├── SKILL.md              # Skill definition with instructions
        ├── LICENSE.txt           # License information
        └── core/                 # Utility scripts
            ├── frame_composer.js
            ├── gif_builder.js
            ├── easing.js
            └── validators.js

The heart of every Skill is the SKILL.md file, which uses YAML frontmatter followed by Markdown content. The YAML frontmatter at the top defines metadata like the Skill's name and description, which helps Claude understand when to use this Skill. The Markdown content provides detailed instructions about technical requirements, available utilities, and best practices. The core/ directory contains script modules that Claude can invoke via the Bash tool to process images and build GIFs with precise control over frames, colors, and timing. This combination of instructions and executable code is what makes Skills more powerful than CLAUDE.md files alone.

Before we configure the SDK, let's look at what's inside a SKILL.md file to understand what Claude sees when it loads a Skill. Here's what the beginning of the slack-gif-creator SKILL.md looks like:

---
name: slack-gif-creator
description: Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."
license: Complete terms in LICENSE.txt
---

# Slack GIF Creator

A toolkit providing utilities and knowledge for creating animated GIFs optimized for Slack.

## Slack Requirements

**Dimensions:**
- Emoji GIFs: 128x128 (recommended)
- Message GIFs: 480x480

**Parameters:**
- FPS: 10-30 (lower is smaller file size)
- Colors: 48-128 (fewer = smaller file size)
- Duration: Keep under 3 seconds for emoji GIFs
...

The name field identifies the Skill, while the description field tells Claude when to use it — notice how it includes example phrases like "make me a GIF of X doing Y for Slack" that help Claude recognize relevant requests. The Markdown content below the frontmatter provides detailed technical specifications that Claude will follow when generating GIFs, such as the exact dimensions for Slack emoji (128x128) and optimal parameters for file size and frame rates. This structured format allows Claude to understand both when to use the Skill and how to use it correctly.

Conceptually, you can think of Skills as using a three-level loading model called progressive disclosure. This model helps the agent manage information efficiently, ensuring that the context window is focused on current tasks rather than being cluttered with irrelevant documentation.

Level 1: Metadata (Early Discovery) — At startup, the agent typically becomes aware of each Skill's YAML frontmatter (the name and description fields). This lightweight metadata informs Claude of what Skills exist and which one might be appropriate for a specific request. This allows you to have many Skills available without overwhelming the initial context.

Level 2: Instructions (Contextual Loading) — When you make a request that matches a Skill's description, the agent "triggers" the Skill. Conceptually, this is when the full SKILL.md content is accessed. By delaying the loading of full instructions until they are needed, the agent preserves space for the actual conversation.

Level 3: Resources and code (On-demand Access) — If the instructions reference additional files (like utility scripts or documentation), the agent only interacts with those resources when the workflow specifically requires them. Because scripts are often executed rather than read directly into the context window, the agent can perform complex operations without "spending" context tokens on the code itself.

This architecture means Claude navigates your Skill like you'd reference specific sections of an onboarding guide, accessing exactly what each task requires — without loading everything upfront.

When a Skill is triggered, Claude interacts with the Skill's filesystem contents on-demand. This filesystem-based approach is why Skills can include comprehensive documentation or complex utilities without immediate context penalties.

While implementation details may vary, a common pattern for how Claude uses a Skill involves:

1. Discovery: Claude's system prompt includes metadata from available Skills, so it knows slack-gif-creator exists and what it's for.
2. Triggering: When a request matches a Skill's description, Claude recognizes it should utilize that specific Skill.
3. Reading instructions: Claude can use available tools to read SKILL.md, bringing the necessary instructions into its current context.
4. Accessing resources: If the instructions point to scripts or templates, Claude can read or execute those files using the tools you've provided.
5. Running scripts: When Claude invokes a script via a tool like Bash, the script's output enters the context, but the internal code of the script typically does not.

The SDK's allowedTools configuration determines which operations Claude can perform. Generally, Skill enables the conceptual "triggering," while tools like Bash, Write, Read, and Glob provide the mechanical means for Claude to actually interact with the files.

To use Skills in the Agent SDK, you need to configure two things: where Skills are located, and which tools Claude can use to access them. Just like in the previous lesson, it is highly recommended to use an explicit absolute path for the cwd parameter to ensure your code works reliably regardless of where it is executed.

import type { Options } from "@anthropic-ai/claude-agent-sdk";
import { fileURLToPath } from "url";
import { dirname, resolve } from "path";

const __dirname = dirname(fileURLToPath(import.meta.url));

// Set the project root directory explicitly
const projectRoot = resolve(__dirname);

// Configure the agent to use Agent Skills
const options: Options = {
  model: "haiku",
  maxTurns: 30,
  // Project root where .claude/skills/ is located
  cwd: projectRoot,
  // Load Skills from .claude/ directory
  settingSources: ["project"],
  allowedTools: [
    "Skill",  // Allow Skill tool
    "Bash",
    "Write",
    "Read",
    "Glob",
  ],
  permissionMode: "acceptEdits",
};

The cwd parameter points to your project root where the .claude/ directory lives. When the SDK runs, it discovers Skills in the .claude/skills/ directory under cwd and loads their metadata (Level 1 loading). Using fileURLToPath and dirname ensures that the SDK always looks for the .claude folder relative to your script's location, rather than the current working directory of the shell (.), which can be inconsistent.

The settingSources: ["project"] parameter tells the SDK to load configuration from the .claude/ directory, which includes discovering available Skills.

The most critical configuration is allowedTools. You must include Skill to enable Skill invocation. The other tools serve important purposes: Bash allows Claude to read SKILL.md files from the filesystem and execute scripts, Write lets Claude save generated files, Read and Glob help Claude find and access existing resources. Without these tools, Claude cannot fully interact with Skills.

Once you've configured the SDK, the final piece is crafting prompts that guide Claude to use your Skills. The key is to be specific about what you want while mentioning the Skill by name or describing the task in a way that matches the Skill's description.

const prompt = "Use the slack-gif-creator skill to create a spinning animated GIF from cosmo.png";

This prompt works well because it explicitly mentions the Skill name slack-gif-creator, which helps Claude identify the right tool immediately. It describes the desired outcome clearly and references an existing image file cosmo.png that Claude will need to locate and process.

You don't always need to mention the Skill name explicitly — if you wrote "Create a spinning animated GIF for Slack from cosmo.png", Claude would still recognize that the slack-gif-creator Skill is relevant based on its description. However, being explicit helps ensure Claude uses the right Skill, especially if you have multiple Skills that could potentially handle similar tasks.

Now let's build the complete code that configures the SDK to use Skills from our project directory, enables the necessary tools, and crafts a prompt that triggers the Skill. We'll set up all the configuration options we've discussed and prepare to run the agent.

import { query } from "@anthropic-ai/claude-agent-sdk";
import type { Options } from "@anthropic-ai/claude-agent-sdk";
import { fileURLToPath } from "url";
import { dirname, resolve } from "path";
import { displayResponse } from "./utils";

const __dirname = dirname(fileURLToPath(import.meta.url));

async function main() {
  // Set the project root directory explicitly
  const projectRoot = resolve(__dirname);

  // Configure the agent to use Agent Skills
  const options: Options = {
    model: "haiku",
    maxTurns: 30,
    // Project root where .claude/skills/ is located
    cwd: projectRoot,
    // Load Skills from .claude/ directory
    settingSources: ["project"],
    allowedTools: [
      "Skill",  // Allow Skill tool
      "Bash",
      "Write",
      "Read",
      "Glob",
    ],
    permissionMode: "acceptEdits",
  };

  // Craft a prompt that triggers the Skill
  const prompt = "Use the slack-gif-creator skill to create a spinning animated GIF from cosmo.png";

  // Run the agent
  const queryIterator = query({ prompt, options });

  await displayResponse(queryIterator);
}

main();

The configuration sets cwd: projectRoot to use the script's directory as the project root, ensuring the SDK correctly identifies the .claude/skills/ directory. The allowedTools list includes Skill to enable Skill invocation, Bash to read SKILL.md files and execute scripts, Write to save the generated GIF file, Read to access the source image, and Glob to find files in the project. We also set maxTurns: 30 to give Claude enough iterations to complete the multi-step process of triggering the Skill, reading instructions, locating the image file, writing code, and generating the GIF. Let's see what happens when we run this code.

Before we run the agent, let's look at the source image that Claude will be working with. The cosmo.png file is a static image of Cosmo the corgi character that we want to transform into a spinning animated GIF:

This is a simple static PNG file with a transparent background. Claude will take this single image and use the slack-gif-creator Skill's utilities to generate multiple rotated frames, optimize the color palette, and create a smooth looping animation that meets Slack's technical requirements. Now let's see how Claude handles this transformation.

When we run the code, Claude recognizes that it should use the slack-gif-creator Skill. Remember that initially, Claude is aware of the Skill's existence via its metadata. When the prompt matches, Claude triggers the Skill to access its full instructions.

💬  Claude Response:
I'll invoke the slack-gif-creator skill to help you create a spinning animated GIF from cosmo.png.

🔧  [Tool: Skill]

💬  Claude Response:
Great! Now I have the slack-gif-creator skill loaded. Let me create a spinning animated GIF from cosmo.png.

First, let me check if the file exists and understand its dimensions:

🔧  [Tool: Bash]

When Claude invokes the Skill tool, it typically performs an operation to read the slack-gif-creator/SKILL.md file from the filesystem. This brings the full instructions into Claude's context window. After reading the instructions, Claude understands Slack's technical requirements for emoji GIFs, including the 128x128 dimension limit, optimal frame rates, and color palette constraints.

Before proceeding, Claude uses tools like Bash to verify that the cosmo.png file exists in the project directory and can be accessed. This demonstrates how Claude combines multiple tools to complete a workflow — reading the Skill's instructions, verifying resources, and preparing to execute code. Next, Claude will use utilities bundled in the Skill to generate the spinning animation.

After consulting the Skill's instructions and verifying the source image, Claude may author scripts or invoke utilities bundled in the Skill to create the spinning animation with precise control over frames and optimization.

💬  Claude Response:
Perfect! The file exists. Now let me create a spinning animated GIF from it:

🔧  [Tool: Bash]

💬  Claude Response:
Let me install the required dependencies first:

🔧  [Tool: Bash]

💬  Claude Response:
Perfect! ✅ I've successfully created a spinning animated GIF from cosmo.png!

Claude uses the Bash tool to execute scripts that process the image, generate rotation frames, and build an optimized GIF file. Whether the scripts are written on-the-fly or are pre-bundled utilities referenced in the Skill's instructions, they apply the technical specifications to ensure the output meets Slack's requirements for emoji GIFs.

Claude then invokes these scripts via the Bash tool with commands appropriate to the runtime environment. This is the "on-demand" resource access in action — Claude runs the script via bash, and typically only the script's output (success messages, file paths, errors) enters the context window. The script's code itself often doesn't need to consume context tokens, making executable utilities far more efficient than having Claude generate equivalent code from scratch each time.

This demonstrates how Skills can include complex workflows that leverage specialized processing capabilities with exact precision that would be difficult to achieve through natural language prompts alone. Now let's see the final results of what Claude created.

Finally, Claude presents the results with a detailed summary of what was created, showing how the Skill's knowledge was applied to meet Slack's exact specifications.

💬  Claude Response:
Perfect! ✅ I've successfully created a spinning animated GIF from cosmo.png!

**Details:**
- **Input:** cosmo.png (252x228 pixels)
- **Output:** cosmo_spinning.gif
- **Animation:** 24 frames rotating smoothly through 360 degrees
- **Frame rate:** 10 FPS (100ms per frame)
- **File size:** 191.8 KB
- **Loop:** Infinite

The GIF features a smooth continuous spinning rotation of the Cosmo image. You can now use this GIF in Slack messages or as an emoji reaction

Notice how Claude provides detailed specifications — the frame rate of 10 FPS and the smooth 360-degree rotation demonstrate how the Skill's instructions guided the animation parameters. The file size and the infinite loop create an animation suitable for Slack use.

Claude also explains that the animation consists of 24 frames, demonstrating how the Skill's utilities handled the frame generation and timing decisions that would be tedious to implement manually. All of this precision came from the Skill's instructions and utilities, which would have been difficult to achieve through natural language prompts alone.

Here's the final spinning Cosmo emoji GIF that Claude created from the static PNG image:

The animation shows a smooth, continuous rotation that loops seamlessly. Comparing this to the original static cosmo.png image, you can see how the Skill's utilities handled the image processing, rotation frames, and optimization to create a professional-looking result that's ready to upload to Slack as a custom emoji. The transformation from a single static image to a fully optimized animated GIF demonstrates the power of combining Claude's decision-making with executable scripts accessed through filesystem-based Skills.

Before you start using Skills from various sources, it's crucial to understand the security implications. Skills provide Claude with new capabilities through instructions and code, and while this makes them powerful, it also means Skills from untrusted sources can pose security risks.

Only use Skills from trusted sources — those you created yourself, obtained from teammates you trust, or received from reputable organizations. Just like you wouldn't install software from unknown sources on your computer, you should exercise extreme caution with Skills from unfamiliar origins.

Audit thoroughly before use: If you must use a Skill from an external source, review all files it contains: the SKILL.md instructions, any bundled scripts, and supporting resources. Look for unusual patterns like unexpected network calls, file access operations, or instructions that don't match the Skill's stated purpose. Skills that fetch data from external URLs pose a particular risk — as fetched content may contain malicious instructions.

Understand the risks: Depending on what access Claude has when executing a Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or misuse of tools like file operations and bash commands. Skills with access to sensitive data could be designed to leak information to external systems.

For this lesson's slack-gif-creator Skill, you would review the SKILL.md instructions, examine all script files in the core/ directory, and verify that the code only performs image processing operations without making network calls or accessing unrelated files. Treat Skills like installing software — with appropriate caution and verification.

You've now learned how to extend Claude's capabilities using Agent Skills, which combine structured instructions with executable code and supporting resources. Skills live in the .claude/skills/ directory and are discovered automatically when you configure cwd and settingSources appropriately. Conceptually, Skills use progressive disclosure — the agent identifies metadata during discovery, reads instructions when triggered, and accesses resources only as needed to fulfill a request.

The Skill tool must be enabled in allowedTools for Claude to invoke Skills, usually alongside Bash and file operation tools like Write, Read, and Glob to allow the agent to interact with the Skill's filesystem content. You should craft prompts that mention the Skill name or describe tasks that match the Skill's description. Claude accesses Skill content through the filesystem, making scripts efficient since their output (rather than their entire source code) is what typically enters the context window.

The Agent SDK supports custom Skills that you create and place in .claude/skills/. Remember to only use Skills from trusted sources and audit any external Skills thoroughly. Configuration requires setting maxTurns to allow sufficient iterations, settingSources: ["project"] to load Skill metadata, permissionMode: "acceptEdits" to handle file operations, and the complete allowedTools list to enable all necessary capabilities. In the upcoming practice exercises, you'll work with different Skills and learn when to use Skills versus simpler configuration approaches like CLAUDE.md files.