#Skills

devboy-tools is not only a tool bundle — it also ships a catalogue of skills: small Markdown recipes that tell an AI agent how to use those tools to accomplish common tasks. Skills are the second half of the "configurable tool bundle" story (see ADR-012).

A skill is a single SKILL.md file with a short YAML frontmatter and a Markdown body. Agents that honour the Agent Skills Standard pick them up from a well-known directory; the CLI puts them there for you.

#Why skills

Tools are verbs — get_issues, create_merge_request, send_message. Skills are short recipes that chain verbs into procedures: "to review a merge request, first fetch the diff, then look up open discussions, then post inline comments with this checklist". Without skills, every agent learns those patterns from scratch on every new project. With skills, the pattern ships next to the tools it calls and every agent picks it up for free.

Skills in devboy-tools follow a few conventions:

• English only — no locale-specific copy in the baseline catalogue.
• CLI-first tool invocation — skills call devboy tools call <name> rather than referring to a specific MCP server. That keeps recipes portable across agents and transports.
• Short bodies — roughly one page each. A skill is a recipe, not a framework.
• Minimal frontmatter — name, description, category, version are required; compatibility, activation, tools are recommended; unknown fields are preserved.

#The shipped catalogue

The baseline catalogue is compiled into the binary and falls into six categories. Every skill is listed with devboy skills list; every skill's full body is printed with devboy skills show <name>.

#Onboarding (the fast path)

devboy onboard is the fastest way to get a curated skill bundle into your AI agent — it auto-detects which agent you actually use and installs a profile-specific bundle. See Quick start for the full flow.

devboy onboard                          # default `dev` bundle
devboy onboard --profile pm             # PM bundle
devboy onboard --profile oncall         # on-call bundle
devboy agents list                      # inspect detected agents

Three profiles ship today:

#Picking skills by hand

Install the self-bootstrap skills into the current project:

devboy skills list --category self-bootstrap
devboy skills install --category self-bootstrap

Install every shipped skill globally so Claude Code / Codex / Cursor / Kimi pick them up regardless of which repository you're in:

devboy skills install --all --agent all

Preview a change without touching disk:

devboy skills install review-mr --agent claude --dry-run

Upgrade previously-installed skills after a devboy upgrade — with no arguments the subcommand upgrades every skill recorded in the local manifest; pass explicit names to scope it to a subset:

devboy skills upgrade                       # every installed skill
devboy skills upgrade review-mr      # just one

#Featured skill: analyze-usage

analyze-usage is the first skill that ships in two parts: a thin Markdown baseline embedded in the binary (installs through the standard catalogue) plus a heavier Python backend (~1 MB sparse-checked-out via curl on first use). The split keeps the devboy binary small and lets the backend evolve independently of the binary release cadence.

It produces graphic monthly / weekly digests of how your AI sessions actually went — biome aquariums (🐋🦈🐬🐟🦐🦠), 8-archetype bars, rhythm, stack palette, DORA radar (CFR + lead time + pushes), friction markers — plus shareable anonymised parquet bundles for further analysis.

See the backend README and GLOSSARY for the full feature set.

#Where skills go

Install targets follow the rules in ADR-013:

• Default — repo-local at <repo>/.agents/skills/<skill>/. Mirrors the .devboy.toml convention.
• --global — ~/.agents/skills/<skill>/.
• --agent claude|codex|cursor|kimi — that agent's conventional path (e.g. ~/.claude/skills/).
• --agent all — every detected agent, plus the vendor-neutral ~/.agents/skills/.
• --local in combination with --agent X puts the install inside the repo instead of the home directory.

If you run devboy skills install outside a git repository and without --global or --agent, the command fails with a clear error listing the flags you might have meant — no silent fallbacks.

#Upgrade safety

Every install target keeps a .manifest.json recording the SHA256 of each installed file. When you upgrade:

• Unchanged files (same hash as the current shipped version) are skipped silently.
• Historical-safe files (hash matches a version we previously shipped) are auto-upgraded to the current version.
• User-modified files (hash matches nothing we ever shipped) are left alone with a warning. Pass --force to overwrite.

This means you can edit installed skills to taste and later upgrade the rest of the catalogue without losing your edits. See ADR-014 for the full lifecycle.

#Session traces

Skills in the self-feedback category read session traces — append-only JSONL files at <target>/.devboy/sessions/<YYYY-MM-DD>/<skill>/<session_id>/trace.jsonl that record what another skill did. Each trace begin gets its own <session_id> subdirectory with a sibling meta.json, so concurrent runs of the same skill on the same day never overwrite one another. Any caller can write into that format via the devboy trace CLI:

result=$(devboy trace begin --skill my-skill)
SESSION_DIR=$(echo "$result" | jq -r .session_dir)
SESSION_ID=$(echo "$result" | jq -r .session_id)

devboy trace event --session-dir "$SESSION_DIR" --session-id "$SESSION_ID" \
  --skill my-skill --phase tool_call \
  --payload '{"tool":"get_issues","args":{"limit":20}}'

devboy trace end --session-dir "$SESSION_DIR" --session-id "$SESSION_ID" \
  --skill my-skill --outcome success --summary "pulled 20 issues"

A central redaction pass strips known credential shapes and env-var-valued secrets before anything lands on disk. Set DEVBOY_TRACE_REDACTION=off to disable it for local debugging only. The format is described in ADR-015.

#Adding your own skill

Skills are plain Markdown. To add one to a project, drop a SKILL.md under <repo>/.agents/skills/<name>/ with a frontmatter block that looks like this:

---
name: my-skill
description: One-sentence summary ending with a period.
category: self-bootstrap            # one of the six categories
version: 1
compatibility: devboy-tools >= 0.18
activation:
  - "phrase agents can use to trigger me"
tools:
  - get_issues
  - create_merge_request
---

# my-skill

...body goes here, roughly one page...

Agents that honour the standard will discover the skill automatically. devboy skills list also picks it up if you point a custom source at the directory (coming in a future release — the initial cut only lists the embedded catalogue).

To contribute a skill upstream, open a pull request that adds crates/devboy-skills/skills/<NN-category>/<name>/SKILL.md in the devboy-tools repository.