> ## Documentation Index > Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt > Use this file to discover all available pages before exploring further. # Scout Skills: Reusable Capabilities for Your AI Agents > Scout Skills are reusable instruction bundles that give agents reliable capabilities. Build once, share across agents, and keep prompts clean. 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: A name and description in frontmatter so the agent can identify the skill and decide when to invoke it. What to do, when to do it, and how to handle errors — a complete playbook for the capability. 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: The Skill's `SKILL.md` is added to the agent's context window at startup. The agent reads the Skill's description and decides whether it matches the current request. The agent follows the Skill's instructions and calls the appropriate tool or API endpoint. 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: ```markdown theme={null} --- 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. Covers the full Scout platform API: Databases, Tables, Documents, Agents, Drive, Syncs, and Usage metrics. 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: | Capability | What it covers | | ---------------------- | --------------------------------------------------------- | | **Databases** | Create, list, query, and delete top-level data containers | | **Tables & Documents** | Full CRUD on structured data, including bulk insert | | **Agents** | List and invoke agents programmatically | | **Drive** | Upload and retrieve files from Scout storage | | **Syncs** | Trigger and monitor data sync jobs from external sources | | **Usage** | Query usage metrics and quotas for your organization | ### `scout-workflow` The `scout-workflow` Skill gives your agent full control over workflow execution and management: | Capability | What it covers | | ------------------------- | --------------------------------------------------------- | | **Run workflows** | Trigger workflow runs with input payloads | | **Stream runs** | Consume real-time streaming output from long-running runs | | **Revisions** | List and inspect workflow revision history | | **CLI workflows as code** | Manage workflow definitions from your terminal | Browse the source at [github.com/scoutos/scout-skills](https://github.com/scoutos/scout-skills). ## Installation Install Skills using the Scout Skills CLI. The following command installs both official Scout Skills from GitHub: ```bash theme={null} 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: ```bash theme={null} npx skills add your-org/your-custom-skill ``` ## Authentication Most Scout Skills call authenticated APIs. Set up your API key before running any Skill: Navigate to **Settings → API Keys** in Scout Studio. Click **Create New Key**, give it a descriptive name (e.g., `agent-skills`), and save it. Copy your private key and export it in your shell or `.env` file: ```bash theme={null} 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](mailto: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 Explore the official `scout` and `scout-workflow` Skills in detail, with example prompts and API references. Build a custom Skill for any API or service your agents need.