Scout Skills

Scout Skills give your agents focused, reliable capabilities they can load on demand. Instead of hoping an agent improvises correctly, you give it a tested playbook — covering exactly which APIs to call, how to authenticate, and how to handle errors.

What are Scout Skills?

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.

Each SKILL.md contains:

• Metadata: A name and description in frontmatter so agents can identify the skill
• Execution guidance: What to do, when to do it, and how to handle errors
• Tool context: API endpoints, authentication requirements, and usage examples

Think of a skill as a specialist you can hand to any agent. The agent doesn’t need to figure out the API — 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:

• 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, not guesses
• 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 collection, create a document, or trigger a workflow run.

Build once, use everywhere

Skills are designed for reuse:

• Share the same skill across multiple agents without duplicating instructions
• Update a capability in one place and all agents that use it benefit 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:

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 endpoint.
4. Respond: The agent returns results and handles errors or follow-up actions 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. 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 critical — it’s what the agent uses to decide whether a given request should use this skill.

Folder layout

A skill lives in its own directory alongside its SKILL.md:

my-skill/
  SKILL.md        # The instruction file
  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:

scout

Covers the full Scout platform API:

• Collections: create, list, query, and delete collections
• Tables and documents: CRUD operations on structured data
• Agents: list and invoke agents programmatically
• Drive: file storage and retrieval
• Syncs: trigger and monitor data sync jobs
• Usage: query usage metrics and quotas

scout-workflow

Covers workflow execution and management:

• Run workflows: trigger runs with input payloads
• Stream runs: consume real-time streaming output from workflow runs
• Revisions: list and inspect workflow revision history
• CLI workflows as code: manage workflow definitions from your terminal

Browse the source: https://github.com/scoutos/scout-skills 

Installation

Install skills using the Scout CLI:

# Install the official Scout skills from GitHub
npx skills add scoutos/scout-skills

After installation, your agents can load skills by name. For example, an agent with access to both scout and scout-workflow will automatically pick the right one based on the task:

• “List all documents in the customers collection” → 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.

Authentication

Most Scout skills call authenticated APIs. To get started:

1. Open Scout and go to Settings → API Keys
2. Create a new key and copy it
3. Store it as an environment variable in your shell or .env file:

export SCOUT_API_KEY="your-api-key-here"

Skills expect credentials to be available as environment variables. The scout and scout-workflow skills both use SCOUT_API_KEY as a Bearer token. Never hardcode credentials in a skill or agent config.

Practical examples

Example 1: Querying a Scout collection

You give an agent the scout skill and ask:

“Find all customers with a plan tier of ‘enterprise’ in the customers collection.”

The agent uses the skill to construct the correct API call, handles pagination, and returns formatted results — without you having to tell it anything about the Scout API.

Example 2: Triggering a workflow run

You 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 built-in skills for Scout
• Creating Skills: Learn to build your own custom skills