---
name: buildkite-plugin-bootstrap
description: >-
  Scaffold a brand-new Buildkite plugin repository from scratch with a correct
  directory layout, plugin.yml, executable hooks, Bats tests, a docker-compose
  test harness, and a CI pipeline. Use when a developer says "create/start/
  bootstrap a new Buildkite plugin", "scaffold a plugin", or needs the initial
  plugin file structure generated for them.
user-invocable: true
argument-hint: <plugin-name> [bash|docker|go|container]
allowed-tools: Read, Write, Edit, Bash
---

# Bootstrap a new Buildkite plugin

This skill generates a complete, ready-to-test Buildkite plugin repository so a
developer goes from nothing to a passing test suite in one step.

## How to run it

There is an executable scaffolder at `scripts/scaffold.sh`. Invoke it with the
plugin's short name (without the `-buildkite-plugin` suffix) and a style:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/scaffold.sh" <plugin-name> <bash|docker|go|container> [target-dir]
```

Examples:
```bash
bash "${CLAUDE_SKILL_DIR}/scripts/scaffold.sh" slack-notify bash ./slack-notify-buildkite-plugin
bash "${CLAUDE_SKILL_DIR}/scripts/scaffold.sh" run-in-docker docker
bash "${CLAUDE_SKILL_DIR}/scripts/scaffold.sh" metrics-reporter go
bash "${CLAUDE_SKILL_DIR}/scripts/scaffold.sh" test-report container
```

The four styles:
- **bash** — host-side hook + reusable `lib/plugin.bash` helpers.
- **docker** — wrap the user's command in a container.
- **go** — compiled binary + downloader-shim hook + GoReleaser.
- **container** — package the plugin's own tool as a Docker image; the hook runs
  it and passes agent creds in (Dockerfile + `bin/run` + wrapper).

If `target-dir` is omitted it defaults to `<plugin-name>-buildkite-plugin` in
the current directory. The script:
- creates the canonical layout (`plugin.yml`, `hooks/`, `tests/`, `.buildkite/`,
  `docker-compose.yml`, `README.md`, `LICENSE`, `.gitignore`);
- for `go`, also emits `main.go` + `main_test.go`, `go.mod`, and
  `.goreleaser.yml`, plus a downloader-shim `hooks/command`;
- for `container`, also emits a `Dockerfile` and `bin/run`, with a
  credential-passing wrapper `hooks/command`;
- computes the correct `BUILDKITE_PLUGIN_<NAME>_*` env-var prefix from the name
  and wires it into the hook/binary + tests so they match;
- makes hook scripts executable;
- optionally runs `git init`.

## What to do after scaffolding

1. **Confirm the style.** Bash = lightweight host-side hooks. Docker = wrap the
   command in a container. Go = compiled binary with a downloader-shim hook, for
   non-trivial logic that deserves real unit tests
   (`reference/compiled-binary-plugins.md`). Container = ship the plugin's own
   tool as a Docker image (`reference/containerized-tool-plugins.md`). If unsure,
   ask the developer.
2. **Edit `plugin.yml`** to declare the real settings (see the
   `buildkite-plugin-dev` skill, `reference/plugin-yml-schema.md`). Keep
   `additionalProperties: false`.
3. **Implement the hook logic** in `hooks/`. Read settings via the generated
   env-var prefix with safe `:-` defaults.
4. **Write tests** for each setting and the failure paths (see the
   `buildkite-plugin-testing` skill).
5. **Run locally:**
   ```bash
   docker-compose run --rm tests
   docker-compose run --rm lint
   ```
6. **Verify current conventions.** Buildkite plugin conventions occasionally
   change — before publishing, confirm against the live docs (see "Stay
   accurate" below).

## Stay accurate (real-time docs)

This skill encodes conventions that are correct as of the last update, but you
should verify version-sensitive details (hook behavior, `plugin.yml` fields,
recommended plugin versions) against the live documentation using WebSearch
scoped to `buildkite.com`, e.g. search "Buildkite writing plugins plugin.yml"
and open https://buildkite.com/docs/pipelines/integrations/plugins/writing.

## Related skills
- `buildkite-plugin-dev` — env-var mapping, hooks, plugin.yml deep reference.
- `buildkite-plugin-testing` — Bats, plugin-tester, plugin-linter, CI.