Skills

Skills are reusable instruction packages that give agents domain-specific expertise. Each skill is a SKILL.md file — the open standard adopted by Anthropic, OpenAI, and the broader agent ecosystem — stored in your workspace registry and delivered to agents automatically when they claim tasks.

Think of skills as npm packages for agent knowledge: structured, versioned, composable. Buildd handles the registry and delivery so you don't need to manage files across machines.

Why Skills

Without skills, agents rely on whatever context is in the task description. This works for simple tasks but breaks down for anything that requires organizational knowledge — deploy policies, code review standards, auth patterns, testing conventions.

Skills formalize this knowledge into reusable packages:

• Consistency — Every agent follows the same deploy runbook, review checklist, or migration workflow
• Composability — Attach multiple skills to a single task (e.g., code-review + security-audit)
• Progressive disclosure — Agents load skill content on-demand, keeping token usage efficient
• Cross-agent compatibility — The SKILL.md format works with Claude Code, Codex, Cursor, Windsurf, and 30+ other agents

The SKILL.md Format

Skills follow the SKILL.md standard. A skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions:

---
name: deploy-policy
description: Production deployment workflow with rollback steps and approval gates
---

# Deploy Policy

## Pre-deploy Checklist
1. All tests pass on the target branch
2. Migration files committed and reviewed
3. Environment variables verified in staging

## Deploy Steps
1. Create a release branch from `main`
2. Run `bun run build` — verify zero errors
3. Push to staging, verify smoke tests
4. Open PR to `production` branch
5. Wait for approval from #deploys channel

## Rollback
If post-deploy monitoring shows errors:
1. Revert the merge commit: `git revert HEAD`
2. Push directly to production branch
3. Post incident summary to #deploys

Required fields:

• name — Lowercase letters, numbers, and hyphens. Max 64 characters. Determines the slug.
• description — What the skill does and when to use it. Max 1024 characters.

Three-tier Loading

Skills use progressive disclosure to stay token-efficient:

A workspace with 50 skills burns ~5k tokens on metadata. The agent loads 2-3 relevant skills per task. This scales far better than loading wiki pages into every prompt.

Bundling Additional Files

Skills can include reference files beyond the main SKILL.md:

code-review/
├── SKILL.md              # Main instructions
├── SECURITY.md           # Security-specific checklist
├── EXAMPLES.md           # Good/bad code examples
└── schemas/
    └── pr-template.md    # PR description template

Reference files are stored in the skill's metadata.referenceFiles field and delivered alongside the SKILL.md when agents claim tasks.

Creating Skills

From the Dashboard

1. Navigate to your workspace
2. Click Skills in the header
3. Click New Skill
4. Fill in:
   • Name — Human-readable name (e.g., "Code Review Standards")
   • Slug — Auto-generated from name, editable (e.g., code-review-standards)
   • Description — When the agent should use this skill
   • SKILL.md Content — The full instructions
5. Click Register Skill

Skills appear in the workspace skills list with enable/disable toggles and expandable content previews.

From Claude Code (MCP)

With the Buildd MCP server connected, ask your agent to register a skill directly:

> Register a skill called "db-migration" with instructions for safe database migrations

The agent calls buildd action=register_skill behind the scenes (an admin-level action). You can also browse existing skills:

> What skills are available in this workspace?

The agent calls buildd action=list_skills and shows you what's registered. This is admin-level too.

Attaching Skills to Tasks

When creating a task, attach skills by their slugs. The agent receives the skill instructions automatically when it claims the task.

From the Dashboard

1. Click New Task from your workspace
2. Select a workspace — available skills load automatically
3. In the Skills section, click skill chips to select which skills this task needs
4. Only enabled skills in the workspace appear as options
5. Create the task — skills are stored with it

From Claude Code (MCP)

> Create a task "Review auth module" with skills code-review and security-audit

The create_task action accepts a skillSlugs array parameter. The server validates that all referenced slugs exist and are enabled. create_task uses a strict parameter allowlist, so a misspelled parameter name (skills, for instance) is rejected outright rather than silently dropped.

In Scheduled Tasks

Skills carry through to scheduled tasks. When setting up a recurring schedule from the dashboard, select skills in the task template — every task created from that schedule automatically includes them.

How Delivery Works

When a worker claims a task with skills attached, Buildd resolves the skill content and delivers it automatically:

1. Worker claims task — the runner polls for available work
2. Server resolves skills — matches skill slugs to the registry, bundles the full SKILL.md content and any reference files
3. Runner writes files — skill content is written to ~/.claude/skills/{slug}/SKILL.md in the user's home directory, not the project directory
4. Agent discovers skills — Claude Code natively discovers ~/.claude/skills/ and loads them using progressive disclosure

~/.claude/
└── skills/
    ├── code-review/
    │   ├── SKILL.md            ← Written before agent starts
    │   └── .hash               ← Content hash for idempotent sync
    └── security-audit/
        ├── SKILL.md
        └── CHECKLIST.md        ← Reference file from metadata

Skills Persist Between Sessions

Delivery is idempotent and deliberately persistent. Two consequences worth understanding:

• Hash-cached. The runner stores a content hash alongside each skill. On the next claim, if the hash matches what is already on disk, the write is skipped entirely. Syncing an unchanged skill costs nothing.
• Never cleaned up. Skill files are not removed when the agent session ends. They stay in ~/.claude/skills/ until they are overwritten by a newer version of the same slug. Because the location is the home directory rather than the repo, skills also never appear as untracked files in your working tree or risk being committed.

To retire a skill from a machine, delete its directory under ~/.claude/skills/ yourself; disabling or deleting the skill in the registry stops future delivery but does not reach back and remove files already written.

The agent's prompt also includes a context section listing installed skills and their paths, so the agent knows what expertise is available.

Managing Skills

Browsing and Editing

Navigate to your workspace and click Skills in the header. From the skills list you can:

• Expand any skill to preview its SKILL.md content
• Toggle skills on or off — disabled skills can't be attached to new tasks
• Delete skills you no longer need

To update a skill's content, use the API PATCH endpoint or re-register it via MCP.

Ecosystem Compatibility

The SKILL.md format is the converging standard across the agent ecosystem. Skills created in Buildd are compatible with:

• Claude Code — Native .claude/skills/ directory discovery
• Claude API — Skills API (/v1/skills endpoints) with code execution
• Claude Agent SDK — Filesystem-based auto-discovery
• Codex (OpenAI) — Same SKILL.md format
• Cursor, Windsurf, Aider, Goose — All support SKILL.md via community tooling

Using Community Skills

The open skills ecosystem has thousands of ready-to-use skills. You can bring them into Buildd by copying their SKILL.md content into your workspace registry via the dashboard or MCP.

Find skills at:

• skills.sh — Curated directory with leaderboard, 55,000+ installs tracked
• GitHub: anthropics/skills — Anthropic's official skill packages
• GitHub: openai/skills — OpenAI's official skill packages
• SkillsMP — 160k+ skills indexed from GitHub with security scanning

You can copy skill content directly into your workspace registry via the dashboard or MCP to share across your team.

Git-Based Skill Development

For teams, the recommended workflow is a private skills repo:

your-org/skills/
├── skills/
│   ├── deploy-policy/SKILL.md
│   ├── code-review/SKILL.md
│   └── service-auth/SKILL.md
├── AGENTS.md                    ← Universal agent discovery
└── README.md

You get versioning (git), review workflow (PRs), and access control (repo permissions). Register skills from this repo into your Buildd workspace to get centralized delivery and task integration.

Writing Effective Skills

A few principles for skills that actually improve agent success rates:

1. Be prescriptive, not descriptive — "Run bun test before committing" beats "tests should pass"
2. Include concrete examples — Show the exact output format, file structure, or code pattern you expect
3. Add checklists — Agents follow checklists reliably. Use - [ ] format.
4. Specify failure modes — "If the migration fails, roll back with git revert HEAD" prevents the agent from guessing
5. Keep it under 5k tokens — If your skill is longer, split into a main SKILL.md and reference files
6. Test empirically — Give an agent nothing but your skill and a task. Did it succeed? If not, the doc is the bug.

Roles — Agent Personas

Skills can be promoted to roles by setting isRole: true. A role is a skill with additional agent configuration:

| connectorRefs | IDs of team connectors this role mounts. This is how a role gets MCP servers. | | defaultBackend | Default agent engine (claude or codex) for tasks routed to this role | | color | Hex color for the role's avatar in the dashboard |

Roles appear on the Team page with live activity (current task, status, duration). Tasks can be routed to a specific role via roleSlug — only workers advertising that role will claim the task.

Connectors — How Roles Get MCP Servers

Every MCP server an agent reaches is a team connector that a role opts into. Credentials are decrypted server-side at claim time and handed to the runner, so they never live on the role record. Attaching one is two steps:

1. Create the connector (team admin), then enable it for the workspace under Settings → Connectors:

curl -X POST https://buildd.dev/api/connectors \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "linear",
    "transport": "http",
    "url": "https://mcp.linear.app/mcp",
    "authMode": "oauth"
  }'

transport is http (needs url) or stdio (needs command, plus optional args and an envMapping of env var name → secret label). authMode is none, header, oauth or assertion. Secret values are stored encrypted in the secrets system.

2. Opt the role into it by adding the connector ID to connectorRefs:

buildd action=update_skill params={
  slug: "builder",
  connectorRefs: ["<connector-id>"],
  canDelegateTo: ["researcher"]
}

You can also manage this from the role editor's Connectors section in the dashboard, which includes an MCP registry browser that creates (or reuses) a team connector and adds the reference in one action.

At claim time the effective set of mounted servers is the intersection of the role's connectorRefs, the connectors enabled for that workspace, and the team's connectors. A task with no roleSlug mounts no connectors at all — this is deliberate least-privilege, and it is the usual explanation for "the agent says the tool isn't available". Use buildd action=list_connectors to check live health; a connector showing auth_expired or disabled will not mount.

Example Role

A "Builder" role with all code tools, one connector, and the ability to delegate research:

{
  "name": "Builder",
  "slug": "builder",
  "isRole": true,
  "content": "# Builder\n\nYou ship features, fix bugs, and manage releases...",
  "model": "standard",
  "color": "#D4724A",
  "allowedTools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Agent", "WebSearch", "WebFetch"],
  "canDelegateTo": ["researcher"],
  "connectorRefs": ["<linear-connector-id>"]
}

The buildd coordination server itself is always available to a worker and never needs a connector — it cannot be overridden by one either.

Managing Roles via MCP

# List all roles
buildd action=list_skills params={ isRole: true }

# Update a role's connectors and delegation
buildd action=update_skill params={ slug: "builder", connectorRefs: ["..."], canDelegateTo: ["researcher"] }

# Create a new role
buildd action=register_skill params={ name: "Ops", isRole: true, content: "...", connectorRefs: ["..."] }

# Inspect connector health
buildd action=list_connectors

# Delete a role
buildd action=delete_skill params={ slug: "ops" }

Default Roles

Every new team is seeded with seven starter roles:

Seeding is team-level, not per-workspace, and is safe to re-run — it will not duplicate a role whose slug already exists on the team. Add more roles as your team grows.

API Reference

For programmatic access, skills are managed through REST endpoints. Authentication works with both session cookies (dashboard) and API keys (Bearer bld_xxx).

Endpoints

Skill Object

{
  "id": "uuid",
  "workspaceId": "uuid",
  "slug": "code-review",
  "name": "Code Review Standards",
  "description": "Security-focused code review checklist",
  "content": "# Code Review\n\n...",
  "source": "manual",
  "metadata": {
    "version": "1.0",
    "author": "platform-team",
    "referenceFiles": {}
  },
  "enabled": true,
  "createdAt": "2026-02-13T00:00:00Z",
  "updatedAt": "2026-02-13T00:00:00Z"
}

The source Field

source is free text, not an enum. It records provenance for humans and is never validated or branched on, so register_skill will store whatever string you pass. The values the product itself writes are:

source may also be null. It is a label only — nothing in delivery, dispatch or permissions reads it.

MCP Tools

Creating a Skill (API)

curl -X POST https://buildd.dev/api/workspaces/{workspace-id}/skills \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review Standards",
    "content": "# Code Review\n\n## Steps\n1. Check for injection vulnerabilities..."
  }'

Creating a Task with Skills (API)

curl -X POST https://buildd.dev/api/tasks \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "ws_xxx",
    "title": "Audit checkout flow UI",
    "description": "Review the checkout pages against the latest Figma designs",
    "skillSlugs": ["ui-audit", "accessibility-check"]
  }'

Team-Level Registry

Skills are registered at the team level and shared across all workspaces in the team. When a worker lists skills, the result merges workspace-scoped skills with team-level skills (workspace skills take precedence by slug).

Workspace-Scoped Skills

Each workspace can have its own skills with additional controls:

• Enabled/disabled — toggle skills per workspace without deleting
• Origin tracking — the origin field is manual or scan. Every write in the product today sets manual; scan is reserved and currently unused.
• Custom content — workspace skills store their own copy of the SKILL.md content

Registering via MCP

Admin-level accounts can register skills through the buildd MCP tool:

buildd({ action: "register_skill", params: { name: "UI Audit", content: "# UI Audit\n\n...", description: "Systematic UI review" } })

Skills as Subagents

Skills can be converted into subagents for the Claude Agent SDK's Task delegation feature. When useSkillAgents is enabled, each skill becomes a named agent that the main worker can delegate to:

agents: {
  'ui-audit': {
    description: 'Systematic UI review against design specs',
    prompt: '<full SKILL.md content>',
    tools: ['Read', 'Grep', 'Glob', 'Bash', 'Edit', 'Write'],
    model: 'inherit',
  }
}

The main worker can then delegate specialized work via the Task tool rather than executing everything in its own context. This keeps context clean and allows parallel execution of independent skill work.

This feature requires the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable.