Build and Install Custom Scout Skills for Your Agents

Custom Skills let you give agents a consistent, reusable playbook for any API or service your team depends on. Rather than re-explaining how to interact with a service in every conversation or agent config, you define the behavior once in a SKILL.md file — and the agent uses it reliably every time the request matches.

When to Create a Custom Skill

Build a custom Skill when:

Your agents need to call an internal or third-party API that isn’t covered by an official Skill.
You find yourself writing the same tool instructions in multiple agent configs.
An agent is making inconsistent API calls that a clear playbook would fix.
You want to share a capability across your team or publish it for others to use.

For Scout platform operations and workflow execution, the official scoutos/scout-skills pack already covers what you need. Custom Skills are for everything outside of that.

The SKILL.md Format

A Skill is a directory containing a SKILL.md file. The file has two parts: a YAML frontmatter block and a free-form Markdown instruction body.

my-skill/
├── SKILL.md       # Agent instructions (required)
└── skill.json     # Tool definitions and metadata (optional)

Frontmatter

The frontmatter defines the Skill’s identity and — most importantly — its activation criteria:

---
name: my-custom-skill
description: >
  Use this skill when the user asks about X, Y, or Z.
  Describe the trigger conditions clearly — the agent
  reads this to decide whether to activate the skill.
---

Write the description from the agent’s perspective: “Use this skill when…” — not as a general summary of what the Skill does. The agent reads this field to decide whether to load the Skill for a given request. Vague descriptions lead to missed activations or false positives.

Instruction Body Sections

The body is free-form Markdown. Structure it with these sections for best results:

Capabilities

A short list of what the Skill can do. Helps the agent understand the Skill’s scope.

When to Use

Explicit trigger conditions. Be precise about the user requests that should activate this Skill.

Available Tools

Each tool or endpoint with method, URL, and parameters. The agent follows this exactly.

Authentication

Required credentials and the environment variable names that hold them.

Usage Examples

Concrete user prompts and the expected agent action. Include the most common cases.

Error Handling

HTTP error codes and what the agent should do for each. Don’t leave the agent to guess.

Complete Example: Weather Skill

Here is a full SKILL.md for a hypothetical weather API integration. Use it as a template for your own Skills.

---
name: weather-skill
description: >
  Use this skill when the user asks about weather, forecasts,
  temperature, rain, or climate conditions for any location.
---

# Weather Skill

Retrieve current weather conditions and multi-day forecasts for any city worldwide.

## Capabilities

- Get current conditions: temperature, humidity, wind speed
- Retrieve 7-day forecasts
- Check active weather alerts

## When to Use

Use this skill when the user:
- Asks about current weather or conditions in a location
- Wants a forecast ("tomorrow", "this week", "next weekend")
- Mentions rain, snow, temperature, or similar weather terms
- Is planning travel and wants weather information

Do not use this skill for climate history, long-range predictions beyond 7 days,
or questions about non-weather environmental conditions.

## Available Tools

### get_current_weather

Fetches real-time conditions for a location.

- Method: `GET`
- URL: `https://api.weather.example.com/current`
- Parameters:
  - `location` (required): City name or lat/lng coordinates
  - `units` (optional): `metric` or `imperial` (default: `metric`)
- Headers:
  - `Authorization: Bearer ${WEATHER_API_KEY}`

### get_forecast

Fetches a multi-day forecast.

- Method: `GET`
- URL: `https://api.weather.example.com/forecast`
- Parameters:
  - `location` (required): City name or coordinates
  - `days` (optional): Number of days, 1–7 (default: `3`)
- Headers:
  - `Authorization: Bearer ${WEATHER_API_KEY}`

## Authentication

This skill requires an API key from weather.example.com.

1. Sign up at https://weather.example.com/signup
2. Copy your API key from Settings → API Keys
3. Export it in your shell or `.env` file:

```bash
export WEATHER_API_KEY=your-api-key-here

Usage Examples

User: “What’s the weather in San Francisco right now?” Action: Call get_current_weather with location: "San Francisco". Present temperature, conditions, and humidity in a friendly summary.

User: “Should I bring an umbrella to Seattle this week?” Action: Call get_forecast with location: "Seattle" and days: 7. Check for rain probability and advise accordingly.

User: “What’s the temperature in Tokyo in Fahrenheit?” Action: Call get_current_weather with location: "Tokyo" and units: "imperial".

Error Handling

401 Unauthorized: The API key is missing or invalid. Ask the user to verify that WEATHER_API_KEY is set correctly.
404 Not Found: The location wasn’t recognized. Ask the user to clarify or try a nearby major city.
429 Rate Limited: Too many requests. Wait a few seconds and retry once. Inform the user if the retry also fails.
Network errors: Inform the user the service is temporarily unavailable and suggest trying again shortly.

## Folder Layout

Keep your Skills organized in a `skills/` directory in your project:

your-project/ └── skills/ ├── weather-skill/ │ ├── SKILL.md │ └── skill.json # optional tool definitions ├── crm-search/ │ └── SKILL.md └── internal-api/ ├── SKILL.md └── README.md

Use lowercase names with hyphens for Skill directory names (e.g., `weather-lookup`, `crm-search`, `slack-notifier`).

## Adding Tool Definitions (Optional)

For Skills that call HTTP endpoints, you can define tools explicitly in a `skill.json` file. This gives the agent structured access to each endpoint with typed parameters.

```json
{
  "name": "weather-skill",
  "version": "1.0.0",
  "tools": [
    {
      "name": "get_current_weather",
      "description": "Get current weather conditions for a location",
      "type": "http",
      "method": "GET",
      "url": "https://api.weather.example.com/current",
      "headers": {
        "Authorization": "Bearer ${WEATHER_API_KEY}"
      },
      "parameters": {
        "location": {
          "type": "string",
          "description": "City name or lat/lng coordinates",
          "required": true
        },
        "units": {
          "type": "string",
          "description": "metric or imperial",
          "required": false,
          "default": "metric"
        }
      }
    },
    {
      "name": "get_forecast",
      "description": "Get a multi-day weather forecast",
      "type": "http",
      "method": "GET",
      "url": "https://api.weather.example.com/forecast",
      "headers": {
        "Authorization": "Bearer ${WEATHER_API_KEY}"
      },
      "parameters": {
        "location": {
          "type": "string",
          "required": true
        },
        "days": {
          "type": "integer",
          "description": "Number of forecast days (1-7)",
          "required": false,
          "default": 3
        }
      }
    }
  ]
}

Use ${VAR_NAME} syntax anywhere in skill.json to reference environment variables at runtime:

{
  "headers": {
    "Authorization": "Bearer ${MY_SERVICE_API_KEY}",
    "X-Tenant-ID": "${TENANT_ID}"
  }
}

Installing Your Skill

Once your files are ready, install the Skill so your agents can use it:

# Install from a local directory
npx skills add ./skills/weather-skill

# Install from a GitHub repository
npx skills add your-org/weather-skill

# List all installed skills
npx skills list

# Remove a skill
npx skills remove weather-skill

Testing Your Skill

Before sharing your Skill, test it with the exact phrases real users will say. A Skill that works for “weather in London” but not “will it rain tomorrow in London?” has a trigger description problem.

Install the skill locally

npx skills add ./skills/your-skill-name

Run test prompts

Try at least five different phrasings of requests the Skill should handle. Confirm the agent activates the Skill for each one.

Test negative cases

Try prompts that should NOT activate the Skill. Confirm the agent doesn’t load it for unrelated requests.

Test error paths

Temporarily set an invalid API key and confirm the agent responds as your Error Handling section documents.

Reinstall after changes

Every time you edit SKILL.md, reinstall the Skill:

npx skills add ./skills/your-skill-name

Best Practices

Write trigger-focused descriptions

The frontmatter description is how the agent decides to activate your Skill. Write it as activation criteria, not marketing copy.

description: >
  Use when the user asks about weather, temperature, forecasts,
  rain, snow, or climate conditions for any city or location.

Be explicit about which tool to call

Don’t make the agent guess which tool to call. Spell it out in your Usage Examples:

**User**: "Is it going to rain in Paris this weekend?"
**Action**: Call `get_forecast` with `location: "Paris"` and `days: 3`.
Check the `precipitation_probability` field and advise accordingly.

Keep instructions actionable

Every instruction should describe an action, not a concept:

Vague	Actionable
”This skill handles weather data."	"When the user asks about weather, extract the location, call `get_current_weather`, and summarize temperature and conditions."
"Handle errors appropriately."	"On 404, ask the user to clarify the location or try a nearby major city.”

One Skill per domain

Resist combining unrelated capabilities into one Skill. An agent that has a “weather and CRM and billing” Skill will activate it incorrectly. Keep each Skill focused on a single domain or service. You can share Skills in three ways:

GitHub Repository

Push your Skill directory to a public or private repo. Others install with npx skills add org/skill-name.

NPM Package

Best for versioned releases with changelogs and semver tags.

Direct Copy

Paste the Skill directory to teammates for quick sharing in a monorepo or shared workspace.

To publish to GitHub:

Create a repository with your Skill files at the root.
Add a README.md with installation instructions and example prompts.
Tag releases with semantic versions (e.g., v1.0.0).

Your teammates install it with:

npx skills add your-org/your-skill-name

Troubleshooting

Issue	What to check
Agent doesn’t activate the Skill	The description doesn’t match the user’s phrasing. Add the exact words and synonyms users say to the `description` frontmatter, then reinstall.
Agent activates but does the wrong thing	Add more prescriptive instructions to `SKILL.md`. Tell the agent exactly which tool to call and what to do with the response. Add an example covering the failing case.
Authentication errors at runtime	Run `echo $YOUR_API_KEY` to confirm the variable is exported. Check that the variable name in `skill.json` matches exactly. Restart your agent session after setting new variables.
Skill installs but doesn’t appear in `npx skills list`	Confirm the `name` field in your frontmatter matches what you expect. The list uses the frontmatter `name`, not the directory name.
Tool calls return unexpected errors	Add an Error Handling section to `SKILL.md` that covers the specific HTTP status codes your API returns. The agent will follow those instructions when errors occur.

Reference

Use the official Scout Skills repository as a model for structure and style. The scout and scout-workflow Skills demonstrate well-written trigger descriptions, authentication setup, and concrete endpoint documentation with parameters:

Repository: github.com/scoutos/scout-skills

Skills Overview

Learn how Skills load, route, and execute inside an agent’s context.

Available Skills

Explore the official Scout and Scout Workflow Skills as reference implementations.

​When to Create a Custom Skill

​The SKILL.md Format

​Frontmatter

​Instruction Body Sections

Capabilities

When to Use

Available Tools

Authentication

Usage Examples

Error Handling

​Complete Example: Weather Skill

​Usage Examples

​Error Handling

​Installing Your Skill

​Testing Your Skill

​Best Practices

​Write trigger-focused descriptions

​Be explicit about which tool to call

​Keep instructions actionable

​One Skill per domain

​Sharing Your Skill

GitHub Repository

NPM Package

Direct Copy

​Troubleshooting

​Reference

Skills Overview

Available Skills

When to Create a Custom Skill

The SKILL.md Format

Frontmatter

Instruction Body Sections

Complete Example: Weather Skill

Usage Examples

Error Handling

Installing Your Skill

Testing Your Skill

Best Practices

Write trigger-focused descriptions

Be explicit about which tool to call

Keep instructions actionable

One Skill per domain

Sharing Your Skill

Troubleshooting

Reference