Skip to main content

​
Integration approaches

The two main approaches to integrating Agent Skills are: Filesystem-based agents operate within a computer environment (bash/unix) and represent the most capable option. Claude Skills are activated when models issue shell commands like cat /path/to/my-skill/SKILL.md. Bundled resources are accessed through shell commands. Tool-based agents function without a dedicated computer environment. Instead, they implement tools allowing models to trigger Claude Skills and access bundled assets. The specific tool implementation is up to the developer.

​
Overview

An Agent Skills-compatible agent needs to:
  1. Discover Claude Skills in configured directories
  2. Load metadata (name and description) at startup
  3. Match user tasks to relevant Agent Skills
  4. Activate Agent Skills by loading full instructions
  5. Execute scripts and access resources as needed

​
Skill discovery

Claude Skills are folders containing a SKILL.md file. Your agent should scan configured directories for valid Agent Skills.

​
Loading metadata

At startup, parse only the frontmatter of each SKILL.md file. This keeps initial context usage low.

​
Parsing frontmatter

function parseMetadata(skillPath):
    content = readFile(skillPath + "/SKILL.md")
    frontmatter = extractYAMLFrontmatter(content)

    return {
        name: frontmatter.name,
        description: frontmatter.description,
        path: skillPath
    }

​
Injecting into context

Include Agent Skill metadata in the system prompt so the model knows what Claude Skills are available. Follow your platform’s guidance for system prompt updates. For example, for Claude models, the recommended format uses XML: 
<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extracts text and tables from PDF files, fills forms, merges documents.</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Analyzes datasets, generates charts, and creates summary reports.</description>
    <location>/path/to/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>
For filesystem-based agents, include the location field with the absolute path to the SKILL.md file. For tool-based agents, the location can be omitted. Keep metadata concise. Each Claude Skill should add roughly 50-100 tokens to the context.

​
Security considerations

Script execution in Claude Skills introduces security risks. Consider:
  • Sandboxing: Run scripts in isolated environments
  • Allowlisting: Only execute scripts from trusted Claude Skills
  • Confirmation: Ask users before running potentially dangerous operations
  • Logging: Record all script executions for auditing

​
Reference implementation

The skills-ref library provides Python utilities and a CLI for working with Claude Skills. For example: Validate an Agent Skill directory: 
skills-ref validate <path>
Generate <available_skills> XML for agent prompts: 
skills-ref to-prompt <path>...
Use the library source code as a reference implementation.