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

# Agent Skills

> Give your agents specialized knowledge and workflows that load on-demand

## Overview

Agent Skills are reusable packages of instructions and bundled files (scripts, templates, references) that give your agents specialized capabilities. Skills use **progressive disclosure** — agents see only a skill's name and description at startup, then load the full instructions on-demand when a matching task comes up.

This keeps system prompts lean while letting agents handle complex, specialized workflows when needed.

## Key Features

<CardGroup cols={2}>
  <Card title="Public & Org-Owned" icon="share-nodes">
    **Org-owned skills** are created and managed by your organization — editable, deletable, and only visible to your org. **Public skills** are platform-managed, available to all organizations with a "Public" badge, and read-only.
  </Card>

  <Card title="Progressive Disclosure" icon="layer-group">
    Agents start with just skill names and descriptions — no prompt bloat. Full instructions load on-demand via the `load_skill` tool, and only the skills relevant to the current task are loaded.
  </Card>

  <Card title="Bundled Files" icon="box-archive">
    Package scripts, templates, references, and assets alongside your instructions. Files are pre-loaded into the Python sandbox at `/home/user/skills/{skill-name}/`, and your SKILL.md tells the agent exactly how to use each one.
  </Card>

  <Card title="Open SKILL.md Format" icon="file-code">
    Skills follow the open [Agent Skills](https://agentskills.io) format — a `SKILL.md` file with YAML frontmatter for metadata and a markdown body for instructions.
  </Card>
</CardGroup>

Both skill types work identically at runtime — agents see no difference between a public skill and an org-owned one. If your org creates a skill with the same name as a public skill, your org's version takes precedence.

### SKILL.md Format

A `SKILL.md` file pairs YAML frontmatter (metadata) with a markdown body (instructions):

```markdown theme={null}
---
name: PDF Report Generator
description: Generate formatted PDF reports from structured data
---

## Instructions

When asked to generate a PDF report:

1. Collect the data from the user
2. Run `scripts/generate_report.py` with the data as JSON input
3. Return the generated PDF to the user

## Available Scripts

- `scripts/generate_report.py` — Takes JSON input, produces formatted PDF
```

## Getting Started

<Steps>
  <Step title="Create a Skill" icon="wand-magic-sparkles">
    Navigate to **Control Hub** → **Skills**, click **"Create Skill"**, then paste or write your SKILL.md content with frontmatter. The skill name and description are automatically parsed from the frontmatter.
  </Step>

  <Step title="Add Bundled Files" icon="upload">
    Open your skill from the Skills list and click **"Upload"** to choose a method (see below). Files appear in a tree view organized by directory, with size information. Reference these files in your SKILL.md instructions by their file path.
  </Step>

  <Step title="Assign Skills to Agents" icon="puzzle-piece">
    Go to **Control Hub** → edit your agent. In the **Skills** section, select which skills this agent can access, then save. The `load_skill` tool is automatically enabled when skills are assigned.
  </Step>
</Steps>

### Upload Methods

When adding bundled files, choose the method that fits:

<Tabs>
  <Tab title="Upload Zip">
    Upload a `.zip` file to replace all bundled files at once (preserves directory structure). You can also drag and drop a `.zip` file directly onto the skill detail page.
  </Tab>

  <Tab title="Upload Folder">
    Select a folder from your computer (preserves directory structure).
  </Tab>

  <Tab title="Add Individual Files">
    Add single files without replacing existing ones.
  </Tab>
</Tabs>

<Tip>
  **Zip upload is the recommended approach** for skills with nested directories (e.g., `scripts/office/pack.py`). If your zip contains a `SKILL.md` at the root, the skill's name, description, and instructions will be updated automatically.
</Tip>

## How It Works

### At Chat Time

<Steps>
  <Step title="Skills are advertised" icon="list-check">
    The agent's system prompt includes an `<available_skills>` section listing skill names and descriptions.
  </Step>

  <Step title="A match triggers a load" icon="bolt">
    When the agent recognizes a task that matches a skill, it calls the `load_skill` tool.
  </Step>

  <Step title="Full instructions return" icon="scroll">
    The tool returns the full SKILL.md instructions plus a listing of bundled files.
  </Step>

  <Step title="The agent executes" icon="rocket">
    The agent follows the instructions, using bundled scripts via `execute_python` as needed.
  </Step>
</Steps>

### Sandbox Integration

When an agent has skills assigned, all bundled files are automatically pre-loaded into the Python sandbox:

```
/home/user/skills/
└── pdf-report-generator/
    ├── SKILL.md
    └── scripts/
        └── generate_report.py
```

The skill directory name is a slugified version of the skill name (e.g., "PDF Report Generator" → `pdf-report-generator`).

## Use Cases

<CardGroup cols={2}>
  <Card title="Document Generation" icon="file-code">
    Bundle Python scripts that generate PDFs, Excel files, or PowerPoint presentations. SKILL.md provides step-by-step instructions for when and how to use each script. The agent collects data from the user, runs the script, and returns the generated file.
  </Card>

  <Card title="Data Processing Pipelines" icon="gear">
    Package data transformation scripts with reference schemas. The agent loads the skill when asked to process specific data formats, and the scripts handle the heavy lifting while the agent manages the workflow.
  </Card>

  <Card title="Specialized Analysis" icon="lightbulb">
    Bundle domain-specific analysis scripts with reference materials — lookup tables, configuration files, or API documentation. The agent uses the skill's instructions to perform complex analysis tasks.
  </Card>

  <Card title="Template-Based Workflows" icon="layer-group">
    Include templates (Excel, markdown, etc.) as bundled files. SKILL.md describes how to fill in each template, and the agent follows the recipe to produce consistent, formatted output.
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Writing SKILL.md" icon="scroll">
    1. **Be specific**: Tell the agent exactly when to use this skill and what steps to follow
    2. **Reference files by path**: Use relative paths like `scripts/setup.py` that match the sandbox structure
    3. **Include examples**: Show sample inputs and expected outputs
    4. **Keep it focused**: One skill per workflow — don't combine unrelated tasks
  </Accordion>

  <Accordion title="Organizing Bundled Files" icon="box-archive">
    1. **Use descriptive names**: `generate_report.py` is better than `script.py`
    2. **Use subdirectories**: Organize with `scripts/`, `templates/`, `references/` as needed
    3. **Keep it lean**: Only include files the agent actually needs (max 100 files per skill)
    4. **Document dependencies**: Note any Python packages your scripts require
  </Accordion>

  <Accordion title="Skill Design" icon="puzzle-piece">
    1. **Single responsibility**: Each skill should handle one type of task well
    2. **Self-contained**: Include everything the agent needs — don't assume external context
    3. **Test the workflow**: Try the full flow (load skill → follow instructions → run scripts) before deploying
    4. **Version via SKILL.md updates**: Update the instructions when your workflow changes
  </Accordion>
</AccordionGroup>

## API Integration

Skills can be managed programmatically through the Aster Agents API. Create skills, upload bundled files, and assign them to agents via API calls.

For detailed API documentation, see the [API Reference](/api-reference) section.

***

Agent Skills let you package complex, repeatable workflows into reusable components. Write the instructions once, bundle the scripts, and any agent with the skill assigned can execute the full workflow on demand.