Skills

Skills are on-demand prompts. Unlike rules (which are always active), skills are invoked by the agent when it encounters a task that matches the skill’s domain.

When to use skills

Use skills for specialized knowledge that’s only relevant sometimes:

• Framework-specific patterns (“how to write a Convex mutation”)
• Integration guides (“Stripe webhook setup”)
• Complex workflows (“database migration checklist”)
• Testing strategies for specific domains

How skills work

1. You write a skill with a name and one or more files (typically SKILL.md)
2. braid install writes it to the agent’s skills directory
3. The agent discovers and invokes the skill when working on a matching task

Skill structure

A skill is a named bundle of files. The primary file is usually SKILL.md:

my-skill/
  SKILL.md       # The main prompt content
  examples/      # Optional reference files
    good.ts
    bad.ts

Where skills are installed

Example

A skill’s SKILL.md includes frontmatter for discovery and categorization:

---
name: api-error-handling
description: Consistent error handling patterns for API routes
license: UNLICENSED
compatibility: opencode
metadata:
  category: "backend"
  tags: "api, errors, validation"
---

# API Error Handling

Use this skill when building API endpoints or error boundaries.

## Pattern

Wrap all route handlers with the `withErrorHandler` helper. Never
return raw error messages to the client — map them to standard codes.

## Reference implementation

​```typescript
export function withErrorHandler(handler: RouteHandler) {
  return async (req: Request) => {
    try {
      return await handler(req);
    } catch (error) {
      if (error instanceof ValidationError) {
        return Response.json(
          { code: "VALIDATION_ERROR", message: error.message },
          { status: 400 }
        );
      }
      console.error("Unhandled error:", error);
      return Response.json(
        { code: "INTERNAL_ERROR" },
        { status: 500 }
      );
    }
  };
}
​```

## When NOT to use

- Background jobs — use retry queues instead of HTTP error codes
- WebSocket handlers — use close codes, not JSON responses

Skills vs rules

Skills are for how to do things. Rules are for what must always be true.

A rule says “all billing mutations must be idempotent.” A skill says “here’s how to implement Stripe webhooks with idempotent mutations.”