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

# Skills

> Create reusable skill packages that bundle instructions, tools, and knowledge — and attach them to any agent.

# Skills

A **skill** is a reusable capability package that bundles together instructions, tools, and knowledge sources into a single unit. Instead of manually configuring the same tools and prompts on multiple agents, create a skill once and attach it to any agent.

## Why Use Skills?

Think of skills like job training modules. A "Calendar Management" skill includes the Google Calendar tool, booking instructions, and availability-checking knowledge. Attach it to any agent and they instantly know how to manage calendars.

Benefits:

* **Reusability** — Create once, use across many agents
* **Consistency** — All agents with the same skill behave the same way
* **Modularity** — Mix and match skills to build capable agents
* **Easy updates** — Update a skill and all agents using it get the improvement

## Skill Structure

| Field                 | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| **Name**              | Display name (e.g., "Appointment Booking")                      |
| **Description**       | What this skill enables the agent to do                         |
| **Category**          | Organizational category (e.g., "productivity", "communication") |
| **Instructions**      | Additional prompt instructions injected into the agent          |
| **Tools**             | Tool types included with this skill                             |
| **Tool Configs**      | Pre-configured tool settings (API keys, defaults)               |
| **Knowledge Sources** | Knowledge sources attached to this skill                        |
| **Priority**          | Execution priority when multiple skills are attached            |
| **Tags**              | Searchable tags for discovery                                   |
| **Icon**              | Visual icon for the dashboard                                   |
| **Public**            | Whether this skill is shared publicly                           |

## Creating a Skill

### From the Dashboard

1. Navigate to your agent's **Skills** tab.
2. Click **Create Skill**.
3. Fill in the skill details:
   * Name and description
   * Select tools to include
   * Add instructions (these are appended to the agent's main instructions)
   * Attach knowledge sources
4. Click **Save**.

### Via the API

```bash theme={null}
curl -X POST https://api.thinnest.ai/api/skills/ \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Booking",
    "description": "Enables the agent to check availability, book appointments, and send confirmations",
    "category": "productivity",
    "instructions": "When a user wants to book an appointment:\n1. Ask for their preferred date and time\n2. Check calendar availability using the Google Calendar tool\n3. Book the appointment\n4. Send a confirmation email via Gmail",
    "tool_types": ["google_calendar", "gmail"],
    "tool_configs": {},
    "knowledge_source_ids": [],
    "is_public": false,
    "tags": ["booking", "calendar", "appointments"]
  }'
```

### Response

```json theme={null}
{
  "id": 42,
  "name": "Appointment Booking",
  "description": "Enables the agent to check availability...",
  "category": "productivity",
  "tool_types": ["google_calendar", "gmail"],
  "is_public": false,
  "created_at": "2026-03-06T10:00:00Z"
}
```

## Attaching Skills to Agents

### From the Dashboard

1. Go to your agent's **Skills** tab.
2. Browse available skills.
3. Click **Attach** on the skills you want.
4. Set the priority (higher priority skills are applied first).
5. Optionally override skill configuration for this specific agent.

### Via the API

```bash theme={null}
# Attach a skill to an agent
curl -X POST https://api.thinnest.ai/api/skills/agent/agent_abc123/attach \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": 42,
    "priority": 1,
    "config_overrides": {}
  }'
```

### Detach a Skill

```bash theme={null}
curl -X POST https://api.thinnest.ai/api/skills/agent/agent_abc123/detach \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": 42
  }'
```

## Managing Skills

### List Available Skills

```bash theme={null}
curl https://api.thinnest.ai/api/skills/available \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

### List Skills on an Agent

```bash theme={null}
curl https://api.thinnest.ai/api/skills/agent/agent_abc123 \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

### Update a Skill

```bash theme={null}
curl -X PUT https://api.thinnest.ai/api/skills/42 \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Appointment Booking",
    "instructions": "Updated booking instructions..."
  }'
```

### Delete a Skill

```bash theme={null}
curl -X DELETE https://api.thinnest.ai/api/skills/42 \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

Deleting a skill automatically detaches it from all agents.

## Skill Priority

When multiple skills are attached to an agent, priority determines the order in which their instructions are injected into the agent's context:

* **Priority 0** (default) — Applied first
* **Priority 1** — Applied second
* Higher numbers = lower priority

If two skills provide conflicting instructions, the higher-priority skill takes precedence.

## Public Skills

Skills can be made public to share them across your organization or with other users:

* **Private skills** (default) — Only visible to you
* **Public skills** — Visible to all users in your organization

Set `is_public: true` when creating or updating a skill.

## Example Skills

### Web Research

```json theme={null}
{
  "name": "Web Research",
  "description": "Enables the agent to search the web and extract content from pages",
  "tool_types": ["duckduckgo", "firecrawl"],
  "instructions": "When asked to research a topic, search the web for relevant information. Extract key facts and provide citations with source URLs."
}
```

### Email Management

```json theme={null}
{
  "name": "Email Management",
  "description": "Read, compose, and send emails via Gmail",
  "tool_types": ["gmail"],
  "instructions": "Help users manage their email. When composing emails, always confirm the recipient and subject before sending. Keep emails concise and professional."
}
```

### Data Analysis

```json theme={null}
{
  "name": "Data Analysis",
  "description": "Analyze CSV data and answer questions about datasets",
  "tool_types": ["duckdb", "csv_tools"],
  "instructions": "When given a dataset, analyze it using SQL queries. Provide clear summaries with key metrics. Include visualizations when helpful."
}
```

## Best Practices

* **One skill per capability** — Don't bundle unrelated tools into one skill.
* **Write clear instructions** — The skill's instructions should be self-contained and specific.
* **Use descriptive names** — "Invoice Processing" is better than "Finance Skill."
* **Test skills individually** — Verify the skill works on a test agent before rolling out.
* **Version through updates** — When updating a skill, all agents using it immediately get the new version.