Authoring a Skill for BoB

How to take a skill from idea to provisioned-into-a-project inside BoB. This guide is the BoB-integration layer on top of the skill-creator skill: skill-creator owns the build mechanics (scope → plan → scaffold → edit → package → iterate); this guide owns the BoB-specific wrapper around it — which surface to choose, where a finished skill lives, how it gets provisioned and promoted, and what to check before it lands.

Don't duplicate skill-creator. When you reach the "write the SKILL.md" step, invoke /skill-creator (or read its SKILL.md) and follow it. This guide deliberately says nothing about anatomy, progressive disclosure, or degrees of freedom — those are skill-creator's job.

1. First decide: skill, command, or agent?

BoB extends Claude Code through three surfaces. Picking the wrong one is the most common authoring mistake, so resolve this before you build anything.

Surface	What it is	Reach for it when…	Lives in
Skill	Auto-loaded procedural knowledge — a workflow, convention, or domain expertise Claude pulls in on its own when the description matches.	The capability is knowledge or a repeatable workflow that should activate implicitly whenever the task matches, with no explicit user invocation.	skills/ (universal) or registry/skills/ (provisioned)
Command	A user-invoked /slash entry point — an explicit, named action.	The user should deliberately trigger a discrete operation by name (and it's fine — or better — that nothing happens unless they ask).	commands/ (universal) or registry/commands/ (provisioned)
Agent	A specialized Task subagent with its own context, model, and tools.	The work needs isolated context or a distinct role/model — fan-out, an adversarial reviewer, a long search that shouldn't pollute the main thread.	agents/ (universal) or registry/agents/ (provisioned)

One concrete example of each:

• Skill — timelord: whenever a doc references "today" or a relative date, Claude should automatically verify the real date. No one types /timelord; it activates on description match. → a skill.
• Command — /start-work: the user explicitly decides "begin a new branch for this issue now." It's a deliberate, named action with side effects. → a command.
• Agent — code-reviewer: a review should run in its own context with a critical role and its own model budget, returning only its verdict to the main loop. → an agent (authored via the agent-builder skill, the agent analogue of skill-creator).

Rule of thumb: implicit knowledge → skill, explicit action → command, isolated role → agent. When a feature wants both an implicit workflow and a /slash entry point, that's two artifacts (a skill plus a thin command that invokes it), not one overloaded skill.

2. Build it

Author the skill with skill-creator — that is the entire build step, and this guide does not repeat it:

/skill-creator

Build it in the registry (registry/skills/<name>/) unless it is genuinely universal (needed by every project — like timelord or commit), in which case it goes in skills/. When in doubt, author it in registry/ — promoting registry → universal later is cheaper than discovering a "universal" skill only one project actually uses.

3. Register it into BoB

A finished skill directory is just files until BoB knows about it. Registration is two moves, depending on where it lives:

Universal skill (skills/)

Universal skills auto-load globally — no manifest, no symlink. They reach the runtime (BOB_HOME, ~/.claude/) when you deploy:

scripts/deploy.sh --dry-run     # preview the sync
scripts/deploy.sh               # sync BOB_SOURCE → BOB_HOME

Registry skill (registry/skills/)

Registry skills are not auto-loaded — they are provisioned per project. Two steps:

1. Sync the source into the runtime so the registry copy exists in BOB_HOME:

   scripts/deploy.sh

2. Add orchestrator metadata to the skill's frontmatter so the recommendation engine (scripts/orchestrator/recommend.js) can suggest it to the right projects:

   applies_to:
     stacks: [cloudflare-workers, d1]      # stacks this skill is for
     project_types: [api, backend]
   recommended_for: [development, ops]
   category: backend-runtime
   required_with: [skills/api-designing]   # optional co-requisites

   This is what lets /provision and the orchestrator answer "is this skill applicable to this project?" — see the Orchestrator Guide.

4. Provision it into a project

Registry skills only become active in a project that declares them. From the target project:

cdprov add skills/<name>     # add to provisions/<project>.json + symlink it in
cdprov status                # confirm it's linked (and not duplicating a global item)
cdprov refresh               # reconcile all symlinks to match the manifest

Or run the /provision command interactively to manage the manifest. The manifest at provisions/<project>.json is the single source of truth for which registry items a project loads; cdprov only ever reconciles symlinks to match it (declarative, idempotent — re-run freely).

Global-aware (#412): if the skill is already global for this machine, cdprovde-dupes it rather than double-provisioning; if a registry skill's name collides with a global one but diverges, cdprov status reports it as a conflict with a resolution hint.

5. Promote a project-local skill upward

If you authored a skill inside one project and want it available to BoB globally, promote it into the source of truth rather than copying files by hand:

cdp     # promote a local item to the global source (BOB_SOURCE)

After cdp lands the skill in BOB_SOURCE (in skills/ or registry/skills/), run scripts/deploy.sh to sync it to the runtime, then cdprov in any project that should load it. (cdl does the inverse — link an existing global item into a project without promoting.)

The full path, end to end:

author (registry/skills/) → deploy.sh → cdprov add (in project)
project-local skill → cdp (promote) → deploy.sh → cdprov add

6. Pre-add validation checklist

Run this checklist before a skill is promoted into BoB (cdp) or added to a manifest (cdprov add). It is the gate the promotion flow references — a skill that fails any line is not ready to land.

• [ ] Frontmatter complete — name and a description that states what the skill does and when to use it (the description is the only thing Claude sees when deciding to auto-load — vague descriptions never fire).
• [ ] Triggers are concrete — the description names the situations/phrases that should activate the skill, not just its topic. "Use when X, Y, or Z" beats "knowledge about X."
• [ ] Kebab-case naming — directory and name are lowercase kebab-case and match each other (skill-authoring, not SkillAuthoring or skill_authoring).
• [ ] Idempotent — any bundled scripts/ are safe to re-run; the skill describes a repeatable workflow with no destructive side effects on a second invocation (the Prime Directive — see skill-creator's IaC principle).
• [ ] No overlap — it doesn't duplicate an existing skill. Check skills/ and registry/skills/ first; if an existing skill is close, extend it instead of forking.
• [ ] Orchestrator metadata (registry skills only) — applies_to / recommended_for / category set, so the recommendation engine can place it.
• [ ] Right surface — re-confirm §1: this is genuinely implicit knowledge, not a disguised command or agent.

See also

• skill-creator — the build mechanics this guide wraps.
• agent-builder — the agent analogue, when §1 points you to an agent.
• Orchestrator Guide — how applies_to metadata drives provisioning recommendations.
• Project Setup Guide — cdi / cdprov wiring for a project.