Skills

Skills are reusable instruction sets that Codebuff can load on-demand. They let you define domain-specific knowledge, workflows, and behaviors that the agent can invoke when needed.

• Reusability — Define instructions once, use them across multiple conversations
• On-demand loading — Skills are only loaded when needed, keeping context clean
• Shareable — Store skills globally or per-project, share with your team
• Slash commands — Every skill becomes a /skill:name command you can trigger directly

Skills live in a skills directory inside .agents/ or .claude/:

.agents/skills/my-skill/

Each skill needs a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: A short description of what this skill does and when to invoke it
license: MIT
metadata:
  category: development
---

# My Skill

Your skill instructions go here...

## Knowledge

Background information and helpful context goes here.

## Instructions

1. Step one
2. Step two
3. Step three

• name (required) — Skill name (1-64 chars, lowercase alphanumeric with hyphens)
• description (required) — Short description (1-1024 chars) shown when browsing skills
• metadata (optional) — Key-value pairs for additional categorization

Skill names must:

• Be 1-64 characters long
• Use only lowercase letters, numbers, and hyphens
• Not start or end with a hyphen
• Not contain consecutive hyphens
• Match the directory name exactly

Valid: git-release, api-design, review2, deploy-prod

Invalid: Git-Release, my--skill, -skill, skill-

Skills are loaded from these locations, in order of priority (later overrides earlier):

1. ~/.claude/skills/ — Global (Claude Code compatible)
2. ~/.agents/skills/ — Global
3. .claude/skills/ — Project (Claude Code compatible)
4. .agents/skills/ — Project (highest priority)

Project skills override global skills with the same name. The .claude/ paths provide compatibility with Claude Code.

Every skill becomes a slash command. Type /skill: to see available skills:

/skill:git-release

This loads the skill's instructions into the conversation.

Codebuff can also load skills automatically via the skill tool when it determines a skill is relevant. The agent sees available skills listed in its tool description and can call:

skill({ name: "my-skill" })

The full SKILL.md content is then loaded into the conversation context.

Here's a practical example of a skill for managing releases:

---
name: git-release
description: Guidelines for creating Git releases with semantic versioning
metadata:
  category: git
  audience: developers
---

# Git Release Workflow

Use this skill when creating a new release.

## Versioning

Follow semantic versioning (semver):
- **MAJOR** (1.0.0) — Breaking changes
- **MINOR** (0.1.0) — New features, backward compatible
- **PATCH** (0.0.1) — Bug fixes, backward compatible

## Release Checklist

1. Ensure all tests pass
2. Update CHANGELOG.md with release notes
3. Bump version in package.json
4. Create a git tag: `git tag v1.2.3`
5. Push with tags: `git push --follow-tags`

## Commit Message Format

Use conventional commits:
- `feat:` — New feature
- `fix:` — Bug fix
- `docs:` — Documentation
- `chore:` — Maintenance

---
name: review
description: Code review checklist and guidelines
metadata:
  category: quality
---

# Code Review Guidelines

## What to Check

1. **Correctness** — Does the code do what it's supposed to?
2. **Tests** — Are there adequate tests?
3. **Security** — Any potential vulnerabilities?
4. **Performance** — Any obvious inefficiencies?
5. **Readability** — Is the code clear and well-documented?

## Feedback Style

- Be constructive and specific
- Suggest alternatives, don't just criticize
- Acknowledge good patterns

Each skill should have a single, clear purpose. Instead of one large "development" skill, create separate skills:

• git-release — Release workflow
• api-design — API design guidelines
• testing — Testing conventions

The description is what Codebuff sees when deciding whether to load a skill. Make it specific:

Good: Guidelines for creating Git releases with semantic versioning and changelog updates

Bad: Git stuff

Metadata helps categorize skills:

metadata:
  category: deployment
  language: typescript
  framework: nextjs

Global skills (~/.agents/skills/):

• Personal workflows
• Cross-project tools
• Your coding preferences

Project skills (.agents/skills/):

• Team conventions
• Project-specific processes
• Codebase-specific knowledge

1. Check the directory structure: project-root/.agents/skills/my-skill/SKILL.md
2. Verify the name in frontmatter matches the directory name
3. Ensure the name follows validation rules (lowercase, hyphens only)
4. Restart Codebuff to reload skills

Ensure your YAML frontmatter:

• Starts and ends with ---
• Has required name and description fields
• Uses valid YAML syntax

---
name: my-skill
description: This is required
---