Skip to main content
Scout Skills give your agents focused, reliable capabilities they can load on demand. Instead of hoping an agent improvises correctly when it encounters an API it hasn’t seen before, you hand it a tested playbook that covers exactly which endpoints to call, how to authenticate, and how to handle errors — every single time.

​
What is a Skill?

A Scout Skill is a reusable instruction bundle that lives in its own folder. At its core is a SKILL.md file that teaches an agent everything it needs to know about a specific capability. The agent reads this file at startup and uses it to decide when and how to act. Each SKILL.md contains three things:

Metadata

A name and description in frontmatter so the agent can identify the skill and decide when to invoke it.

Execution Guidance

What to do, when to do it, and how to handle errors — a complete playbook for the capability.

Tool Context

API endpoints, authentication requirements, payload shapes, and usage examples the agent follows directly.
Think of a Skill as a specialist you can hand to any agent. The agent doesn’t need to figure out the API from scratch — the Skill already knows it.

​
Why Use Skills?

​
Consistent, predictable behavior

Without a Skill, agents can improvise in ways that are hard to predict or debug. A Skill gives them a tested playbook with clear rules:
  • Clear triggers — The agent knows exactly when to use the Skill vs. when to skip it.
  • Correct API patterns — The agent follows known endpoints and payload shapes instead of guessing.
  • Safer execution — Auth, rate limits, and failure handling are all documented up front.
For example, instead of an agent constructing a Scout API call from scratch and potentially getting the payload wrong, the scout Skill tells it precisely how to query a database, create a document, or trigger a workflow run.

​
Build once, use everywhere

Skills are designed for reuse across your entire agent fleet:
  • Share the same Skill across multiple agents without duplicating instructions.
  • Update a capability in one place and every agent that uses it benefits immediately.
  • Compose focused Skills — one for Scout core APIs, another for workflow execution, another for a third-party integration.

​
Keep agent prompts clean

When every tool’s documentation lives in the agent prompt, it gets unwieldy fast. Skills let you separate concerns:
  • Complex tool instructions live in the Skill, not in the agent config.
  • Agents reference the Skill by name — short and readable.
  • You can update or swap Skills without touching agent configurations at all.

​
How Skills Work

When an agent has access to a Skill, here is the flow from request to response:
1

Load

The Skill’s SKILL.md is added to the agent’s context window at startup.
2

Route

The agent reads the Skill’s description and decides whether it matches the current request.
3

Execute

The agent follows the Skill’s instructions and calls the appropriate tool or API endpoint.
4

Respond

The agent returns results and handles errors or follow-up actions exactly as the Skill documents.
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Agent     │────▶│    Skill    │────▶│   Tools     │
│             │     │  (SKILL.md) │     │  (APIs)     │
└─────────────┘     └─────────────┘     └─────────────┘
       │                                        │
       └────────────────────────────────────────┘
                   Results flow back
The agent stays in control of the conversation — the Skill just tells it what to do when a particular capability is needed.

​
Skill Structure

​
The SKILL.md file

Every Skill is defined by a SKILL.md file. The file has two parts: a YAML frontmatter block and a free-form Markdown instruction body. Here is what a well-structured Skill looks like: 
---
name: my-skill
description: What this skill does and when to use it. Be specific — this is how
  the agent decides whether to invoke the skill.
---

# Skill Instructions

## When to use this skill
Describe the user requests or situations that should trigger this skill.

## Available tools and endpoints
List the APIs, endpoints, or tools this skill exposes.

## Authentication
Explain what credentials are required and how to pass them.

## Usage examples
Show concrete request/response patterns the agent should follow.

## Error handling
Document common errors and how the agent should respond to them.
A good description in the frontmatter is the single most important line in your Skill. It’s what the agent reads to decide whether a given request should use this Skill. Write it as activation criteria: “Use this skill when the user asks about X, Y, or Z.”

​
Folder layout

A Skill lives in its own directory alongside its SKILL.md: 
my-skill/
  SKILL.md        # The instruction file (required)
  README.md       # Optional: human-readable docs
Multiple Skills can live in the same repository, which makes it easy to install a whole capability set in one command.

​
Official Scout Skills

The scoutos/scout-skills repository provides two production-ready Skills you can install immediately.

scout

Covers the full Scout platform API: Databases, Tables, Documents, Agents, Drive, Syncs, and Usage metrics.

scout-workflow

Covers workflow execution: trigger runs, stream real-time output, inspect revision history, and manage workflows as code.

​
scout

The scout Skill gives your agent access to Scout’s core data and platform APIs:
CapabilityWhat it covers
DatabasesCreate, list, query, and delete top-level data containers
Tables & DocumentsFull CRUD on structured data, including bulk insert
AgentsList and invoke agents programmatically
DriveUpload and retrieve files from Scout storage
SyncsTrigger and monitor data sync jobs from external sources
UsageQuery usage metrics and quotas for your organization

​
scout-workflow

The scout-workflow Skill gives your agent full control over workflow execution and management:
CapabilityWhat it covers
Run workflowsTrigger workflow runs with input payloads
Stream runsConsume real-time streaming output from long-running runs
RevisionsList and inspect workflow revision history
CLI workflows as codeManage workflow definitions from your terminal
Browse the source at github.com/scoutos/scout-skills.

​
Installation

Install Skills using the Scout Skills CLI. The following command installs both official Scout Skills from GitHub: 
npx skills add scoutos/scout-skills
After installation, your agents load Skills by name and automatically pick the right one based on the task:
  • “List all documents in the customers database” → uses scout
  • “Run the onboarding-workflow with this user data” → uses scout-workflow
You can also install Skills from any GitHub repository using the same org/repo format: 
npx skills add your-org/your-custom-skill

​
Authentication

Most Scout Skills call authenticated APIs. Set up your API key before running any Skill:
1

Open Scout Settings

Navigate to Settings → API Keys in Scout Studio.
2

Create a new key

Click Create New Key, give it a descriptive name (e.g., agent-skills), and save it.
3

Set the environment variable

Copy your private key and export it in your shell or .env file:
export SCOUT_API_KEY="your-api-key-here"
Both the scout and scout-workflow Skills use SCOUT_API_KEY as a Bearer token automatically. Never hardcode credentials in a Skill or agent configuration.
Store API keys in environment variables or a secrets manager — never in source code, Skill files, or agent configs. Anyone with access to a private key can make authenticated requests on behalf of your organization.

​
Practical Examples

​
Example 1: Querying a Scout database

Give an agent the scout Skill and ask:
“Find all customers with a plan tier of ‘enterprise’ in the customers database.”
The agent uses the Skill to construct the correct API call, handles pagination, and returns formatted results — without you having to explain anything about the Scout API.

​
Example 2: Triggering a workflow run

Give an agent the scout-workflow Skill and ask:
“Run the lead-enrichment workflow for this new contact: name=Jane Doe, email=jane@example.com”
The agent uses the Skill to invoke the workflow with the right payload shape and reports back with the run ID and status.

​
Example 3: Using Skills in a multi-agent setup

You have a coordinator agent that delegates to specialized sub-agents. One sub-agent gets the scout Skill for data access, another gets scout-workflow for automation. Each agent stays focused on what it knows, and the coordinator routes requests to the right one.

​
Next Steps

Available Skills

Explore the official scout and scout-workflow Skills in detail, with example prompts and API references.

Creating Skills

Build a custom Skill for any API or service your agents need.