> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmskills.org/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Integrate Agent Skills

> Learn how to integrate Agent Skills: discover, load metadata, match tasks, activate instructions, and execute scripts securely.

## 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:

```xml theme={null}
<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](https://github.com/agentskills/agentskills/tree/main/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.