Skills

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

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

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.

Assign a skill

Assign the skill in .polpo/agents/designer/agent.json:

{
  "skills": ["frontend-design"],
  "team": "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.

Activate a skill for one request

Callers can explicitly prioritize one or more skills already assigned to the effective agent or loop:

{
  "agent": "designer",
  "messages": [{ "role": "user", "content": "Build the settings page." }],
  "polpo": {
    "skills": ["frontend-design"]
  }
}

Activation is additive and lasts only for that request. Other assigned skills remain available, and the agent configuration is not changed. Polpo rejects names that are not assigned to the effective agent or loop. Clients may expose shortcuts such as /frontend-design, but must send the selected names through polpo.skills; the runtime does not parse slash-prefixed message text. With the React SDK, pass the selection on the individual message:

await chat.sendMessage("Build the settings page.", {
  skills: ["frontend-design"],
});

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

const skills = await client.getSkills();
await client.assignSkill("frontend-design", "designer");
await client.unassignSkill("frontend-design", "designer");

See Skills ecosystem for the distinction between runtime skills and skills installed into coding agents.

Getting Started

Platform

Agents

Orchestration

SKILL.md

Assign a skill

Activate a skill for one request

API

​SKILL.md

​Assign a skill

​Activate a skill for one request

​API

SKILL.md

Assign a skill

Activate a skill for one request

API