Skills

Skills are markdown instruction files that give an agent specialized knowledge. They’re like mini system prompts that you can mix and match across agents — encoding team conventions, domain workflows, or specialized knowledge without bloating every agent’s config.

What’s a Skill?

A skill is a directory containing a SKILL.md file:

.polpo/skills/typescript-patterns/
  SKILL.md

The SKILL.md file has YAML frontmatter and a markdown body:

---
name: typescript-patterns
description: TypeScript best practices and common patterns
allowedTools:
  - read
  - write
  - edit
---

## TypeScript Patterns

When writing TypeScript code, follow these conventions:

- Use `const` by default, `let` only when reassignment is needed
- Prefer interfaces over type aliases for object shapes
- Use discriminated unions for state machines
...

Field	Required	Description
`name`	No	Skill identifier — falls back to directory name if omitted
`description`	Yes	Human-readable summary (shown in listings and pickers)
`allowedTools`	No	Tools the agent should have when this skill is active

The name field is optional. If you omit it, Polpo uses the directory name. This means skills installed from skills.sh work out of the box — they only need name and description in frontmatter.

Installing Skills

Polpo can install skills directly from GitHub repositories, compatible with the skills.sh ecosystem (5,000+ skills from Vercel, Anthropic, Expo, and more).

CLI
TUI
HTTP API

# Install from a GitHub repo (all skills in the repo)
polpo skills add vercel-labs/agent-skills

# Install specific skills only
polpo skills add vercel-labs/agent-skills --skill frontend-design --skill web-design-guidelines

# Install to global pool (shared across all projects)
polpo skills add anthropics/skills --global

# Install from a local directory
polpo skills add ./my-local-skills

/skills add vercel-labs/agent-skills
/skills add anthropics/skills frontend-design skill-creator

curl -X POST http://localhost:3000/api/v1/projects/my-project/skills/add \
  -H "Content-Type: application/json" \
  -d '{ "source": "vercel-labs/agent-skills", "skillNames": ["frontend-design"] }'

Skills are cloned from the repo and copied into .polpo/skills/. From there, you assign them to specific agents.

Skill Pool

Polpo discovers skills from two locations (in priority order):

Priority	Location	Scope	Description
1	`.polpo/skills/`	Project	Managed by `polpo skills add` — shared pool
2	`~/.polpo/skills/`	Global	User-level skills (shared across all projects)

Project skills take priority. If a project and global skill share the same name, the project one wins.

Assigning Skills to Agents

This is Polpo’s key differentiator: skills from the pool are assigned to specific agents. Your frontend-dev gets React patterns, your reviewer gets security knowledge, your backend-dev gets database patterns — each agent gets exactly what it needs. Three ways to assign: CLI command:

polpo skills assign react-patterns frontend-dev

In config — list skill names in the agent’s skills array:

{
  "name": "frontend-dev",
  "skills": ["react-patterns", "css-conventions"]
}

Via symlinks — link from the agent’s skill directory to the pool:

ln -s ../../skills/react-patterns .polpo/agents/frontend-dev/skills/react-patterns

The polpo skills assign command creates the symlink for you — it’s equivalent to the manual ln -s approach.

How Skills Are Loaded

When an agent starts a task:

Polpo checks .polpo/agents/<name>/skills/ for symlinked skills (hard enforcement)
If no symlinks exist, it resolves AgentConfig.skills[] names against the pool (soft/config-based)
The matched skill markdown is injected into the agent’s system prompt
Skills with allowedTools also inform which tools the agent receives

Skills that aren’t loaded for a particular agent are still mentioned by name — so the agent knows they exist but doesn’t get their content.

Managing Skills

CLI
TUI
HTTP API

# List all skills with agent assignments
polpo skills list

# Remove a skill from the pool
polpo skills remove frontend-design

# Remove a global skill
polpo skills remove frontend-design --global

/skills              → interactive picker
/skills list         → inline summary
/skills remove react-patterns

# List skills
curl http://localhost:3000/api/v1/projects/my-project/skills

# Remove a skill
curl -X DELETE http://localhost:3000/api/v1/projects/my-project/skills/frontend-design

# Assign to agent
curl -X POST http://localhost:3000/api/v1/projects/my-project/skills/react-patterns/assign \
  -H "Content-Type: application/json" \
  -d '{ "agent": "frontend-dev" }'

Creating a Skill

mkdir -p .polpo/skills/my-skill

Then create .polpo/skills/my-skill/SKILL.md:

---
name: my-skill
description: What this skill teaches the agent
---

Your instructions here...

That’s it — Polpo discovers it automatically.

Skills are a great way to keep agent instructions DRY. Instead of copy-pasting the same conventions into every agent’s systemPrompt, create a skill once and assign it to the agents that need it.

Orchestrator Skills

Everything above describes agent skills — skills loaded into worker agents when they run tasks. But the orchestrator itself is also an LLM, and it can have its own skills too. Orchestrator skills live in a separate pool from agent skills:

Priority	Location	Scope	Description
1	`.polpo/.agent/skills/`	Project	Orchestrator skills for this project
2	`~/.polpo/.agent/skills/`	Global	Orchestrator skills shared across all projects

The .agent directory (singular, dot-prefixed) is the orchestrator’s own config directory — separate from agents/ (plural) which contains worker agent configs.

Why Separate Pools?

Agent skills teach agents how to do their job — coding patterns, domain workflows, framework conventions, review criteria. Orchestrator skills teach the orchestrator how to manage work — how to create skills, how to structure teams, how to plan missions. Mixing them would pollute each other’s context.

Skill Discovery in Chat

The orchestrator automatically discovers all available agent skills and lists them in its context. When you create or update agents via chat, the orchestrator will proactively suggest relevant skills — for example, recommending a frontend-design skill when you create a frontend agent, or a testing skill for a QA agent.

Installing Orchestrator Skills

CLI
HTTP API
Chat

# Install from a GitHub repo
polpo skills orchestrator add anthropics/skills --skill skill-creator

# Install all skills from a repo
polpo skills orchestrator add vercel-labs/skills

# List orchestrator skills
polpo skills orchestrator list

# Remove an orchestrator skill
polpo skills orchestrator remove skill-creator

# List orchestrator skills
curl http://localhost:3000/api/v1/projects/my-project/skills/orchestrator

# Install from source
curl -X POST http://localhost:3000/api/v1/projects/my-project/skills/orchestrator/add \
  -H "Content-Type: application/json" \
  -d '{ "source": "anthropics/skills", "skillNames": ["skill-creator"] }'

# Create a custom orchestrator skill
curl -X POST http://localhost:3000/api/v1/projects/my-project/skills/orchestrator \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-workflow", "description": "Custom workflow", "content": "..." }'

# Remove
curl -X DELETE http://localhost:3000/api/v1/projects/my-project/skills/orchestrator/skill-creator

The orchestrator has built-in tools for managing its own skills:

list_orchestrator_skills — see what’s installed
create_orchestrator_skill — write a new skill from scratch
update_orchestrator_skill — modify an existing skill
remove_orchestrator_skill — delete a skill
install_orchestrator_skill — install from a GitHub repo

Loading Behavior

By default, all orchestrator skills in the pool are loaded into the orchestrator’s system prompt. If you want to restrict which skills are active, use the orchestratorSkills setting:

{
  "settings": {
    "orchestratorSkills": ["skill-creator", "find-skills"]
  }
}

When orchestratorSkills is omitted (the default), every skill discovered in .polpo/.agent/skills/ and ~/.polpo/.agent/skills/ is loaded.

Skills Index (Tags & Categories)

Skills can be tagged and categorized using the skills index — a local metadata file (.polpo/skills-index.json) that stores tags and categories for each skill. This is separate from the SKILL.md frontmatter, so you can tag any skill — including third-party skills that don’t include metadata.

Adding Tags and Categories

CLI
HTTP API
Chat

# Set tags and category for a skill
polpo skills tag frontend-design -t frontend react ui css -c development

# Set only category
polpo skills tag testing -c quality

# View current tags/category
polpo skills tag frontend-design

# Clear tags
polpo skills tag frontend-design --clear-tags

# Update a skill's index entry
curl -X PUT http://localhost:3000/api/v1/projects/my-project/skills/frontend-design/index \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["frontend", "react", "ui"], "category": "development" }'

# Get the full skills index
curl http://localhost:3000/api/v1/projects/my-project/skills/index

The orchestrator has a tag_skill tool:

tag_skill({ name: "frontend-design", tags: ["frontend", "react"], category: "development" })

Index Format

The index is stored in .polpo/skills-index.json:

{
  "frontend-design": {
    "tags": ["frontend", "react", "ui", "css"],
    "category": "development"
  },
  "testing": {
    "tags": ["testing", "vitest", "coverage"],
    "category": "quality"
  }
}

Tags and categories are shown in polpo skills list, in the Web UI (with filters), and in the orchestrator’s skill listing. The orchestrator uses them to suggest relevant skills when creating or updating agents.

skills.sh Compatibility

Polpo is compatible with the skills.sh ecosystem. polpo skills add clones a GitHub repository, discovers all SKILL.md files in standard locations (skills/, .agents/skills/, .claude/skills/, and any subdirectory), and copies them into Polpo’s .polpo/skills/ pool. The key difference from other agents: skills.sh agents are single-agent tools (Claude Code, Cursor, Codex), so every installed skill is always active. Polpo adds per-agent assignment — you install skills into the shared pool, then assign them to the agents that need them.

Examples

Code Review Skill

---
name: code-review
description: Code review standards and quality criteria
allowedTools:
  - read
  - glob
  - grep
---

## Code Review

When reviewing code, check for:

1. **Security** — no hardcoded secrets, proper input validation, SQL injection prevention
2. **Error handling** — all async operations have try/catch, errors are logged with context
3. **Performance** — no N+1 queries, efficient data structures, memoization where appropriate
4. **Readability** — clear variable names, comments on non-obvious logic, small functions

Project Conventions Skill

---
name: project-conventions
description: Project-specific conventions and patterns
---

## Conventions

- All files use TypeScript strict mode
- Database queries go in `src/db/` — never inline SQL in route handlers
- API responses follow `{ ok: boolean, data?: T, error?: string }` format
- Tests live next to source files: `Button.tsx` → `Button.test.tsx`
- Imports use path aliases: `@/db`, `@/routes`, `@/utils`

Core

Agent Capabilities

Sharing & Registry

Mission Execution

Human-in-the-Loop

Quality & Recovery

Security

What’s a Skill?

Installing Skills

Skill Pool

Assigning Skills to Agents

How Skills Are Loaded

Managing Skills

Creating a Skill

Orchestrator Skills

Why Separate Pools?

Skill Discovery in Chat

Installing Orchestrator Skills

Loading Behavior

Skills Index (Tags & Categories)

Adding Tags and Categories

Index Format

skills.sh Compatibility

Examples

Code Review Skill

Project Conventions Skill

Core

Agent Capabilities

Sharing & Registry

Mission Execution

Human-in-the-Loop

Quality & Recovery

Security

​What’s a Skill?

​Installing Skills

​Skill Pool

​Assigning Skills to Agents

​How Skills Are Loaded

​Managing Skills

​Creating a Skill

​Orchestrator Skills

​Why Separate Pools?

​Skill Discovery in Chat

​Installing Orchestrator Skills

​Loading Behavior

​Skills Index (Tags & Categories)

​Adding Tags and Categories

​Index Format

​skills.sh Compatibility

​Examples

​Code Review Skill

​Project Conventions Skill

What’s a Skill?

Installing Skills

Skill Pool

Assigning Skills to Agents

How Skills Are Loaded

Managing Skills

Creating a Skill

Orchestrator Skills

Why Separate Pools?

Skill Discovery in Chat

Installing Orchestrator Skills

Loading Behavior

Skills Index (Tags & Categories)

Adding Tags and Categories

Index Format

skills.sh Compatibility

Examples

Code Review Skill

Project Conventions Skill