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

# Skills

> Installable instruction bundles assigned to agents

A skill is a directory containing `SKILL.md` and optional supporting files. Project skills live under `.polpo/skills/{name}/`.

Polpo Cloud uses progressive loading: the system prompt lists assigned skill names, while the automatically registered `skill_list` and `skill_read` tools expose metadata and load a relevant body on demand. The OSS runtime's direct prompt builder injects the full body of assigned skills. In both cases an agent can only access skills assigned in its `skills` array.

## SKILL.md

```yaml theme={null}
---
name: frontend-design
description: Review and implement production frontend interfaces
allowed-tools:
  - browser_*
  - read
---

Put the operating instructions and domain knowledge here.
```

The runtime parser reads `name`, `description`, and `allowed-tools`. The directory name is used when `name` is omitted. `tags` and `category` are project index metadata stored separately in `.polpo/skills-index.json`; they are not runtime frontmatter fields.

<Note>
  A skill's `allowed-tools` is metadata. Assigning a skill does not bypass the agent's `allowedTools` policy; enable required tools on the agent too. Cloud's `skill_list` and `skill_read` are added automatically for agents with assigned skills.
</Note>

## Assign a skill

Local `.polpo/agents.json` entries wrap the agent config:

```json theme={null}
[
  {
    "agent": {
      "name": "designer",
      "skills": ["frontend-design"]
    },
    "teamName": "design"
  }
]
```

Run `polpo deploy` to sync local skills and assignments. To install a repository directly through the Agent API, use `POST /v1/skills/add` or `client.installSkills(source)` with a supported source such as a GitHub repository URL.

## API

| Method   | Path                         | Description                         |
| -------- | ---------------------------- | ----------------------------------- |
| `GET`    | `/v1/skills`                 | List skills and assignments         |
| `GET`    | `/v1/skills/{name}/content`  | Read the parsed skill content       |
| `POST`   | `/v1/skills/create`          | Create a skill                      |
| `DELETE` | `/v1/skills/{name}`          | Delete a skill                      |
| `POST`   | `/v1/skills/{name}/assign`   | Assign a skill to an agent          |
| `POST`   | `/v1/skills/{name}/unassign` | Remove an assignment                |
| `POST`   | `/v1/skills/add`             | Install skill bundles from a source |
| `GET`    | `/v1/skills/index`           | Read tags and categories            |
| `PUT`    | `/v1/skills/{name}/index`    | Update tags and category            |

```typescript theme={null}
const skills = await client.getSkills();
await client.assignSkill("frontend-design", "designer");
await client.unassignSkill("frontend-design", "designer");
```

See [Skills ecosystem](/docs/ecosystem/skills-registry) for the distinction between runtime skills and skills installed into coding agents.