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

Public & Org-Owned

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.

Progressive Disclosure

Agents start with just skill names and descriptions — no prompt bloat. Full instructions load on demand with the Skills tool, and only the skills relevant to the current task are loaded.

Bundled Files

Package scripts, templates, references, and assets alongside your instructions. When the agent loads the skill, its files are copied into the Python sandbox at /home/user/skills/{skill-name}/, and your SKILL.md tells the agent how to use each one.

Open SKILL.md Format

Skills follow the open Agent Skills format — a SKILL.md file with YAML frontmatter for metadata and a markdown body for instructions.

Both skill types work identically at runtime — agents see no difference between a public skill and an org-owned one. Skill names are unique within your organization, including public skill names: you can’t create an org skill with the same name as a public one.

SKILL.md Format

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

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

1. Create a Skill

   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.

2. Add Bundled Files

   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.

3. Turn on Skills for your agent

   Skills are on by default for new agents. To check, open the agent in Control Hub and find the Skills section. When it’s on, the agent sees every skill in your organization plus every public skill, and can load, create, and publish them. When it’s off, the agent doesn’t know skills exist.

Upload Methods

When adding bundled files, choose the method that fits:

Upload Zip

Upload a .zip or .skill file to replace all bundled files at once (preserves directory structure). You can also drag and drop it directly onto the skill detail page.

Upload Folder

Select a folder from your computer (preserves directory structure).

Add Individual Files

Add single files without replacing existing ones.

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.

How It Works

At Chat Time

1. Skills are advertised

   The agent’s system prompt lists every skill’s name and one-line description.

2. A match triggers a load

   When the agent recognizes a task that matches a skill, it loads it with the Skills tool (action: "load").

3. Full instructions return

   The tool returns the full SKILL.md instructions and copies the bundled files into the sandbox.

4. The agent executes

   The agent follows the instructions, using bundled scripts via execute_python as needed.

Sandbox Integration

A skill’s files are in the sandbox only after the agent loads it. Loading copies them here:

/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

Document Generation

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.

Data Processing Pipelines

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.

Specialized Analysis

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.

Template-Based Workflows

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.

Best Practices

Writing SKILL.md

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

Organizing Bundled Files

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

Skill Design

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

Locking a Skill

Skills start unlocked. Click Lock on a skill’s page, or ask an agent to lock it, to protect it. Editing a skill changes every agent that loads it, and a lock prevents that. While it’s locked, only its author or an org admin can edit its SKILL.md, change its bundled files, publish over it, or delete it. Everyone else, and every agent, can still load and use it. When an agent can’t publish over a locked skill, it can publish its version as a new skill.

API Integration

Skills can be managed programmatically through the Aster Agents API: create skills and upload bundled files. Any agent with Skills turned on can then use them.

For detailed API documentation, see the API Reference.

---

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

Editing skills with an agent

Agents can improve skills, not just use them. Ask an agent to change one, and it:

1. Loads the skill with the Skills tool (action: "load"), which puts its files in skills/{skill-name}/.
2. Edits the files with Run Code, keeping SKILL.md’s instructions in step with the code.
3. Publishes with action: "publish", which makes a new version of the skill.

Loading again keeps the agent’s unsaved edits. If someone published a newer version in the meantime, the agent is told instead of having its edits replaced. action: "status" shows the skill’s publication history and any local changes, and an earlier version can be loaded and republished to bring it back. Public skills are read-only, and locked skills can only be published by their author or an admin.