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

# Build and Install Custom Scout Skills for Your Agents

> Build custom Scout Skills for any API or service your agents need. Define a SKILL.md with execution guidance and error handling for reliability.

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`](/skills/available-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:

```yaml theme={null}
---
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.
---
```

<Tip>
  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.
</Tip>

### Instruction Body Sections

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

<CardGroup cols={2}>
  <Card title="Capabilities" icon="list">
    A short list of what the Skill can do. Helps the agent understand the Skill's scope.
  </Card>

  <Card title="When to Use" icon="compass">
    Explicit trigger conditions. Be precise about the user requests that should activate this Skill.
  </Card>

  <Card title="Available Tools" icon="wrench">
    Each tool or endpoint with method, URL, and parameters. The agent follows this exactly.
  </Card>

  <Card title="Authentication" icon="key">
    Required credentials and the environment variable names that hold them.
  </Card>

  <Card title="Usage Examples" icon="terminal">
    Concrete user prompts and the expected agent action. Include the most common cases.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    HTTP error codes and what the agent should do for each. Don't leave the agent to guess.
  </Card>
</CardGroup>

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

````markdown theme={null}
---
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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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.

<Steps>
  <Step title="Install the skill locally">
    ```bash theme={null}
    npx skills add ./skills/your-skill-name
    ```
  </Step>

  <Step title="Run test prompts">
    Try at least five different phrasings of requests the Skill should handle. Confirm the agent activates the Skill for each one.
  </Step>

  <Step title="Test negative cases">
    Try prompts that should NOT activate the Skill. Confirm the agent doesn't load it for unrelated requests.
  </Step>

  <Step title="Test error paths">
    Temporarily set an invalid API key and confirm the agent responds as your Error Handling section documents.
  </Step>

  <Step title="Reinstall after changes">
    Every time you edit `SKILL.md`, reinstall the Skill:

    ```bash theme={null}
    npx skills add ./skills/your-skill-name
    ```
  </Step>
</Steps>

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

<CodeGroup>
  ```yaml Good theme={null}
  description: >
    Use when the user asks about weather, temperature, forecasts,
    rain, snow, or climate conditions for any city or location.
  ```

  ```yaml Too vague theme={null}
  description: Handles weather data for locations.
  ```
</CodeGroup>

### Be explicit about which tool to call

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

```markdown theme={null}
**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.

## Sharing Your Skill

You can share Skills in three ways:

<CardGroup cols={3}>
  <Card title="GitHub Repository" icon="github">
    Push your Skill directory to a public or private repo. Others install with `npx skills add org/skill-name`.
  </Card>

  <Card title="NPM Package" icon="box">
    Best for versioned releases with changelogs and semver tags.
  </Card>

  <Card title="Direct Copy" icon="files">
    Paste the Skill directory to teammates for quick sharing in a monorepo or shared workspace.
  </Card>
</CardGroup>

To publish to GitHub:

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

Your teammates install it with:

```bash theme={null}
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](https://github.com/scoutos/scout-skills)

<CardGroup cols={2}>
  <Card title="Skills Overview" icon="stars" href="/skills/overview">
    Learn how Skills load, route, and execute inside an agent's context.
  </Card>

  <Card title="Available Skills" icon="list" href="/skills/available-skills">
    Explore the official Scout and Scout Workflow Skills as reference implementations.
  </Card>
</CardGroup>