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_register_skill behind the scenes. You can also browse existing skills:

> What skills are available in this workspace?

The agent calls buildd_list_skills and shows you what's registered.

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 buildd_create_task tool accepts a skills array parameter. The server validates that all referenced slugs exist and are enabled.

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 — Local UI 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. Local UI writes files — Skill content is written to .claude/skills/{slug}/SKILL.md in the project directory before the agent starts
4. Agent discovers skills — Claude Code natively discovers .claude/skills/ directories and loads them using progressive disclosure
5. Cleanup — Skill files are removed from the project directory after the agent session ends

project/
└── .claude/
    └── skills/
        ├── code-review/
        │   └── SKILL.md        ← Written before agent starts
        └── security-audit/
            ├── SKILL.md        ← Written before agent starts
            └── CHECKLIST.md    ← Reference file from metadata

This file-based delivery follows the Claude Code convention. 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:

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.

Example Role

A "Builder" role with the buildd MCP server, all code tools, and the ability to delegate research:

{
  "name": "Builder",
  "slug": "builder",
  "isRole": true,
  "content": "# Builder\n\nYou ship features, fix bugs, and manage releases...",
  "model": "inherit",
  "color": "#D4724A",
  "allowedTools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Agent", "WebSearch", "WebFetch"],
  "canDelegateTo": ["researcher"],
  "mcpServers": {
    "buildd": {
      "type": "http",
      "url": "https://buildd.dev/api/mcp",
      "headers": { "Authorization": "Bearer ${BUILDD_API_KEY}" }
    }
  },
  "requiredEnvVars": { "BUILDD_API_KEY": "buildd-api-key" }
}

MCP server configs use ${VAR} syntax — the actual secret values are stored encrypted in the secrets system and injected at claim time.

Managing Roles via MCP

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

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

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

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

Default Roles

New workspaces are automatically seeded with two starter roles:

• Builder — All code tools, buildd MCP, delegates to researcher
• Researcher — Read/search tools, buildd MCP, delegates to builder

These provide immediate value out of the box. 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"
}

Source Types

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",
    "skills": ["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 — manual (user-created) or promoted (from team registry)
• 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.