buildkite-plugin-bootstrap

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

Examples:

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:

   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).