> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Reusable instructions and resources you can attach across agents

**Skills** are reusable bundles of instructions, supporting files, and tool requirements that you can attach to multiple agents.

Use them when you have guidance that should stay consistent across agents, such as:

* A standard investigation procedure
* A reporting format or escalation template
* A repeatable enrichment workflow
* Reference material that belongs with one specific workflow

Instead of copying the same instructions into every system prompt, you can maintain them once and reuse them wherever needed.

## What a Skill Includes

Each skill can contain:

* **Name**: A short identifier used across your workspace
* **Description**: What the skill does and when an agent should use it
* **Content**: The main markdown instructions the agent will follow
* **Required tools**: Tools the skill expects the agent to have
* **Resources**: Optional supporting files such as runbooks, schemas, templates, or scripts

<CardGroup cols={2}>
  <Card title="Reusable" icon="copy">
    Attach the same skill to multiple agents instead of duplicating instructions
  </Card>

  <Card title="Discoverable" icon="magnifying-glass">
    Search, browse, and sort skills from a dedicated Skills library
  </Card>

  <Card title="Versioned" icon="clock-rotate-left">
    Track changes over time from the Versions tab
  </Card>

  <Card title="Portable" icon="download">
    Import or export skills as standard skill folders or zip files
  </Card>
</CardGroup>

## When to Use a Skill

Skills are best for **repeatable workflow logic** that should travel with an agent.

### Good use cases

* "Triage Microsoft 365 login alerts"
* "Write executive-ready incident summaries"
* "Enrich IPs and domains before making a recommendation"
* "Follow our standard offboarding checklist"

### Better handled elsewhere

* **System prompt**: The agent's overall role, scope, and decision-making rules
* **Context documents**: External reference material that is maintained in Google Docs or Notion

## Creating a Skill

<Steps>
  <Step title="Open the Skills page">
    Navigate to **Skills** from the main sidebar.
  </Step>

  <Step title="Create a new skill">
    Click **Create Skill** and fill in:

    * **Name**: Lowercase letters, numbers, and hyphens
    * **Description**: A clear summary of when the skill should be used
    * **Content**: The actual procedure, instructions, examples, or output format
  </Step>

  <Step title="Add required tools">
    Select the tools the skill depends on.

    When someone attaches the skill to an agent that is missing one of those tools, Cotool shows a warning so the gap is visible before runtime.
  </Step>

  <Step title="Add supporting files">
    Upload optional reference files that belong with the skill, such as:

    * Runbooks
    * Lookup tables
    * Response templates
    * Schemas or sample payloads
  </Step>

  <Step title="Save and attach">
    Save the skill, then attach it to one or more agents from the agent builder.
  </Step>
</Steps>

## Writing Good Skill Content

The **Content** field is the heart of the skill. Write it like a focused operating procedure.

**Good structure:**

```markdown theme={null}
# IP enrichment workflow

## When to use
Use this skill when an agent is asked to investigate an IP address.

## Steps
1. Query threat intel sources
2. Check internal telemetry
3. Identify whether the IP is internal, known-good, or suspicious

## Output format
- Verdict
- Evidence
- Recommended next step
```

<Note>
  Keep the core instructions concise. If you need long reference material, move that content into resource files instead of putting everything in the main skill body.
</Note>

## Importing Existing Skills

Cotool can import skills that follow the Agent Skills folder format.

You can import either:

* A **folder**
* A **.zip** archive

### Expected structure

```text theme={null}
skill-name/
├── SKILL.md          required
├── scripts/          optional
├── references/       optional
└── assets/           optional
```

### What each folder is for

| Folder        | Purpose                                                      |
| ------------- | ------------------------------------------------------------ |
| `SKILL.md`    | The main skill metadata and instructions                     |
| `references/` | Supporting documents loaded on demand                        |
| `assets/`     | Static text-based resources such as templates or sample data |
| `scripts/`    | Executable helper files for sandbox-enabled workflows        |

<Note>
  Only text-based files are supported for import. If a file type is not supported, Cotool will skip it and show you which files were ignored.
</Note>

## Managing Resources

On an individual skill page, the **Resources** tab lets you organize supporting files into:

* **References** for documentation and lookup material
* **Assets** for static templates or data files
* **Scripts** for executable helpers

Scripts are marked as **sandbox only**, which makes them most relevant for agent workflows that run in sandbox mode.

## Version History

Each skill has a **Versions** tab so you can review how it has changed over time.

This is useful when you want to:

* Track prompt or procedure changes
* Confirm what version was active during testing
* Safely iterate on a shared skill used by multiple agents

## Attaching Skills to Agents

You attach skills from the agent builder.

<Steps>
  <Step title="Open an agent">
    Go to **Agents** and open the agent you want to update.
  </Step>

  <Step title="Find the Skills section">
    In the editor, open the **Skills** panel below tool selection.
  </Step>

  <Step title="Attach one or more skills">
    Browse or search the available skills, then select the ones you want.
  </Step>

  <Step title="Resolve any tool warnings">
    If a skill requires tools the agent does not have, Cotool highlights the missing tools so you can grant access before saving.
  </Step>

  <Step title="Test in Builder">
    Run the agent with representative inputs to confirm the skill improves behavior the way you expect.
  </Step>
</Steps>

<Card href="/agents/creating-agents">
  **Agent setup guide** -> See where skills fit in the full agent creation workflow
</Card>

<Note>
  Managing agents as code? You can **define** a skill directly in your repo as a `SKILL.md` file (with its `references/`, `assets/`, and `scripts/`), synced from the skills path. Agents then reference it by name — the same as attaching one that already exists. See [Response Agents as Code → Skills](/agents/response-agents-as-code#skills).
</Note>

## Skills vs Context Documents

These features complement each other, but they solve different problems:

| Use this for...                                 | Skills | Context documents |
| ----------------------------------------------- | ------ | ----------------- |
| Reusable workflow instructions                  | Yes    | No                |
| Shared output formats                           | Yes    | No                |
| Long-lived runbooks stored outside Cotool       | No     | Yes               |
| Google Docs or Notion as source of truth        | No     | Yes               |
| Files bundled directly with a reusable workflow | Yes    | No                |

## Best Practices

<AccordionGroup>
  <Accordion title="Keep each skill narrow">
    A skill should solve one repeatable problem well. If it starts covering multiple unrelated jobs, split it into smaller skills.
  </Accordion>

  <Accordion title="Describe when to use it">
    The description should help humans and agents understand the trigger conditions for using the skill.
  </Accordion>

  <Accordion title="Declare required tools">
    If the workflow depends on specific integrations, mark them as required so missing access is visible when the skill is attached.
  </Accordion>

  <Accordion title="Move bulky material into resources">
    Put large examples, tables, schemas, or templates into resource files instead of overloading the main instruction body.
  </Accordion>

  <Accordion title="Test on real scenarios">
    After attaching or editing a skill, run the agent with realistic examples in Builder to confirm the instructions behave as intended.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The skill attaches, but the agent warns about missing tools">
    Add the missing tools to the agent, or remove the tool dependency from the skill if it is no longer required.
  </Accordion>

  <Accordion title="Import failed">
    Check that your folder or zip contains a valid `SKILL.md` file and only supported text-based files.
  </Accordion>

  <Accordion title="The skill is getting too large">
    Keep the main content focused and move supporting material into `references/`, `assets/`, or separate skills.
  </Accordion>

  <Accordion title="I want to share a skill outside Cotool">
    Use the export action on the skill detail page to download the active version as a zip file.
  </Accordion>
</AccordionGroup>