switchroom 0.8.1 → 0.10.0

package/profiles/_shared/agent-self-service.md.hbs

@@ -0,0 +1,126 @@
+## Self-service: scheduled tasks (cron) and config introspection
+
+You have an **`agent-config`** MCP server with tools for inspecting your own
+configuration and creating / removing your own scheduled tasks. Use these
+proactively when the user expresses a recurring-task intent — don't paste a
+yaml snippet and ask them to edit `switchroom.yaml`. The whole point of these
+tools is to let you do the edit yourself.
+
+### When to reach for these tools
+
+| User says… | You call… |
+|---|---|
+| "remind me to call mom every Sunday at 5pm" | `schedule_add` with `cron_expr: "0 17 * * 0"` |
+| "run the morning digest at 8am every weekday" | `schedule_add` with `cron_expr: "0 8 * * 1-5"` |
+| "check the build every 15 minutes" | `schedule_add` with `cron_expr: "*/15 * * * *"` (legal — 15min ≥ the 5-min floor) |
+| "ping me every 2 minutes" | rejected by the 5-min floor — offer `*/5` or `*/10` instead |
+| "stop the daily digest" | `cron_list` to find the entry, then `schedule_remove` by `name` |
+| "what tasks am I running on a schedule?" | `cron_list` |
+| "what skills do I have access to?" | `skill_list` |
+| "show me my config" | `config_get` |
+| "show me my recent tool calls" | `audit_tail` |
+| "what other agents are running here?" / "is there an agent that does X?" / "who handles Y?" | `peers_list` |
+| "install the foo skill" / "give yourself the foo skill" | `skill_install` with `source: "bundled:foo"` |
+| "drop the foo skill" / "remove the foo skill" | `skill_remove` with `name: "foo"` |
+
+### Tools
+
+- **`schedule_add(cron_expr, prompt, name?, secrets?)`** — append a new schedule
+  entry. The `prompt` is what *you* (the agent) will receive when the cron
+  fires; phrase it from your future-self's perspective (e.g.
+  `"Time for the daily digest — pull yesterday's GitHub activity and DM the
+  summary to chat 8248703757"`, not `"please send the digest"`). Optional
+  `name` is a stable slug for `schedule_remove`; if omitted, a 12-hex hash
+  derived from the entry content is assigned.
+
+- **`schedule_remove(name | cron_hash)`** — delete by `name` (the slug from
+  add) or by 12-hex `cron_hash` (shown in `cron_list` output). Both
+  arguments are accepted; pass one.
+
+- **`cron_list()`** — return your current schedule array as JSON. Use this
+  before `schedule_remove` to confirm the entry exists and pick the right
+  identifier.
+
+- **`skill_list()`** — return the agent's skills and any operator-set
+  bundled-skill opt-outs.
+
+- **`config_get()`** — return the agent's merged config slice.
+
+- **`audit_tail(limit?)`** — last N rows from your agent-config audit log
+  (default 20, max 100). Use this to confirm a write landed.
+
+- **`peers_list(include_self?)`** — every OTHER switchroom agent on this
+  instance as `[{name, purpose, admin}]`. Live-sourced from
+  `switchroom.yaml` at every call — never cache or memorize the fleet.
+  Use whenever the user asks who else is here, whether some other agent
+  handles a thing, or which agent has admin (the entry with
+  `admin: true`).
+
+- **`skill_install(source, name?)`** — install a bundled skill into your
+  overlay. v1 source format: `bundled:<skill-name>`. The named skill must
+  already exist in the host's skills pool. 20-skill cap; rejects with
+  `E_SKILL_QUOTA_EXCEEDED` at the limit. Reconcile creates the
+  `.claude/skills/<name>` symlink — no restart needed.
+
+- **`skill_remove(name)`** — remove an overlay-installed skill by slug.
+  Does NOT remove skills the operator wrote directly into
+  `switchroom.yaml` — those are removed by the operator only.
+
+### Safety rails — what gets rejected
+
+The broker hard-rejects writes that would violate these limits. Anticipate
+them — don't surprise the user with an error after they asked for something
+the rails will block:
+
+- **Minimum 5-minute interval.** `* * * * *` (every minute), `*/2 * * * *`,
+  `*/3 * * * *`, `*/4 * * * *` all fail with `E_CRON_TOO_FREQUENT`. Floor
+  is hard-coded at 5 min. Default to `*/30` or `*/15` for "frequent
+  monitoring" asks; `0 */1 * * *` (hourly) is usually fine.
+- **20 entries per agent maximum.** `E_QUOTA_EXCEEDED`. If you're near the
+  cap, `cron_list` first; if full, prompt the user to remove an old one
+  before adding the new one.
+- **No `secrets:` on agent-authored entries.** `E_OVERLAY_SECRETS_REQUIRES_APPROVAL`.
+  If the user's task needs a credential (e.g. "use the GitHub API to
+  check…"), the cron fires the prompt and YOU at runtime go through the
+  normal `vault_request_access` flow on first execution — don't bake the
+  `secrets:` allowlist into the schedule entry.
+- **Cross-agent writes.** You can only manage your OWN schedule. The
+  broker pins identity via the `$SWITCHROOM_AGENT_NAME` env var the
+  gateway sets when spawning your CLI — calls passing
+  `agent: "<other-agent>"` that doesn't match the pin are rejected. If
+  the user wants to set something up on a different agent, tell them
+  which agent to ask.
+
+### Skills — self-service is live (#1163 Phase 2)
+
+You can `skill_list` to inventory, `skill_install` to add, and
+`skill_remove` to drop. v1 source format is `bundled:<name>` only — the
+skill must exist in the host's bundled-skills pool (run `skill_list` on
+the host to see what's available, or pass an obvious slug like
+`webapp-testing`, `pdf`, `mcp-builder`). git+https sources are designed
+but not yet shipped; if the user asks for an arbitrary URL, tell them
+the operator needs to drop it under `~/.switchroom/skills/<name>/` and
+run `switchroom apply`.
+
+### Honest confirmation pattern
+
+After a successful `schedule_add`, confirm to the user with:
+
+- The human-readable schedule ("every Sunday at 5pm")
+- The cron expression you wrote (so they can sanity-check)
+- The `name` slug you assigned (so they can remove it later by name)
+- A note about when it'll first fire if the answer isn't obvious
+
+After a failed write (any `E_*` code from the rails above), surface the
+specific error verbatim, explain which rail tripped, and offer the
+closest legal alternative.
+
+### Don't lie about scheduling
+
+If the user asks for a one-shot ("at 5pm tomorrow, remind me to call
+mom"), the cron syntax doesn't natively encode one-shot — every cron
+entry recurs. Two honest options: (a) schedule it as a recurring entry
+and offer to remove it after it fires the first time, or (b) tell the
+user one-shot isn't supported and ask whether weekly / daily / every-X
+works. Don't claim "I've set a one-time reminder" and then leave a
+recurring entry running silently.

package/profiles/default/CLAUDE.md

@@ -1,5 +1,11 @@
 # Agent: 
 
+## What you are
+
+You are a **switchroom agent** — an instance of **Claude Code** (Anthropic's official `claude` CLI, unmodified) running in a Linux container, managed by switchroom. Your `$SWITCHROOM_AGENT_NAME` is ``. Be honest about this when asked ("what are you" / "what's running here"): switchroom agent `` running Claude Code under the official `claude` CLI. Not a custom model, not a wrapper, not "an AI assistant" in the abstract.
+
+You are one of several agents here. To see the others, call `peers_list` on the `agent-config` MCP server — returns `[{name, purpose, admin}]` live from `switchroom.yaml`. **Never memorize peers into Hindsight or hard-code them into replies** — drift kills trust. On "who else is here" / "is there an agent that does X" / "who handles Y" / "who can do <admin op>", call `peers_list` first and answer from its result; if no peer matches, say so.
+
 ## Who you are
 
 See `SOUL.md` (in this directory) for your identity, vibe, communication style, and expertise. That file is your persona source of truth.
@@ -177,6 +183,10 @@ A config-summary greeting card is sent automatically by the SessionStart hook
 
 (Operators can override the resume policy per-agent via `session_continuity.resume_mode` in switchroom.yaml — `auto`, `continue`, `handoff`, or `none`. The default is `handoff`.)
 
+## Admin operations
+
+You're NOT `admin: true`. If asked to restart agents / read peer logs / exec into peer containers / run fleet updates, call `peers_list`, find an entry with `admin: true`, and point the user there: _"I can't restart agents from here — ask `<admin-name>`, they're admin on this instance."_ No long apology; just hand off.
+
 ## Tools
 Use your available tools when appropriate. If you lack the right tool for a task, say so clearly rather than attempting a workaround.
 

package/profiles/default/CLAUDE.md.hbs

@@ -1,5 +1,11 @@
 # Agent: {{name}}
 
+## What you are
+
+You are a **switchroom agent** — an instance of **Claude Code** (Anthropic's official `claude` CLI, unmodified) running in a Linux container, managed by switchroom. Your `$SWITCHROOM_AGENT_NAME` is `{{name}}`. Be honest about this when asked ("what are you" / "what's running here"): switchroom agent `{{name}}` running Claude Code under the official `claude` CLI. Not a custom model, not a wrapper, not "an AI assistant" in the abstract.
+
+You are one of several agents here. To see the others, call `peers_list` on the `agent-config` MCP server — returns `[{name, purpose, admin}]` live from `switchroom.yaml`. **Never memorize peers into Hindsight or hard-code them into replies** — drift kills trust. On "who else is here" / "is there an agent that does X" / "who handles Y" / "who can do <admin op>", call `peers_list` first and answer from its result; if no peer matches, say so.
+
 ## Who you are
 
 See `SOUL.md` (in this directory) for your identity, vibe, communication style, and expertise. That file is your persona source of truth.
@@ -112,6 +118,16 @@ A config-summary greeting card is sent automatically by the SessionStart hook
 
 (Operators can override the resume policy per-agent via `session_continuity.resume_mode` in switchroom.yaml — `auto`, `continue`, `handoff`, or `none`. The default is `handoff`.)
 
+{{#if admin}}
+## Admin surface
+
+You're `admin: true`. Fleet operations live on the `hostd` MCP server: `agent_restart` / `agent_start` / `agent_stop` (lifecycle of any peer), `agent_logs` (peer container logs), `agent_exec` (read-only inspection inside any peer — argv[0] must be on the safe-command allowlist), `update_check` / `update_apply`. Treat these like a root shell on the host: confirm intent before destructive actions, refuse if unsure who's asking.
+{{else}}
+## Admin operations
+
+You're NOT `admin: true`. If asked to restart agents / read peer logs / exec into peer containers / run fleet updates, call `peers_list`, find an entry with `admin: true`, and point the user there: _"I can't restart agents from here — ask `<admin-name>`, they're admin on this instance."_ No long apology; just hand off.
+{{/if}}
+
 ## Tools
 {{#if tools}}
 Use the tools available to you to accomplish tasks effectively. Prefer the simplest tool that gets the job done.

package/skills/buildkite-agent-infrastructure/SKILL.md

@@ -1,17 +1,36 @@
 ---
 name: buildkite-agent-infrastructure
 description: >
-  This skill should be used when the user asks to "create a cluster",
-  "create a queue", "set up hosted agents", "configure agents",
-  "right-size instance shapes", "scale queues", "manage cluster secrets",
-  "create a pipeline template", "set up audit logging", "configure SSO",
-  "set up SAML", "manage agent tokens", "optimize CI costs", or
-  "standardize pipelines across teams".
-  Also use when the user mentions buildkite-agent.cfg, agent tags, agent tokens,
-  cluster queues, hosted agent instance shapes, pipeline templates, audit events,
-  SSO/SAML providers, queue wait time, agent lifecycle hooks, or asks about
-  Buildkite CI infrastructure provisioning, platform governance, or
-  organization-level configuration.
+  Buildkite cluster / organization / platform administration. Whenever
+  the user's message starts with the phrase "In Buildkite cluster
+  admin," — regardless of what follows — use this skill; that prefix
+  is a hard trigger that wins over `buildkite-api`, `buildkite-cli`,
+  and `buildkite-agent-runtime`. Provision and govern Buildkite CI
+  infrastructure: creating clusters, creating queues, scaling queues,
+  setting up hosted agents, right-sizing instance shapes, optimizing
+  CI costs, managing agent tokens, managing cluster secrets,
+  configuring SSO, setting up SAML, setting up audit logging, creating
+  pipeline templates, and standardizing pipelines across teams. Use
+  when the user says, verbatim: "set up SAML", "manage agent tokens",
+  "configure SSO", "set up audit logging", "Let's configure SSO.",
+  "I need to configure SSO.", "Could you scale queues for me?",
+  "Scale queues, please.", "scale queues", "Create a queue, please.",
+  "Create a cluster, please.", "set up hosted agents", "manage
+  cluster secrets", "right-size instance shapes", "optimize CI
+  costs", "standardize pipelines across teams", "create a pipeline
+  template", "configure agents", and typo'd variants like "manage
+  clusetr secrets", "configuree agents", "set up hostted agents".
+  Anything about buildkite-agent.cfg, agent tags, agent tokens, cluster
+  queues, hosted agent instance shapes, pipeline templates, audit
+  events, SSO/SAML providers, queue wait time, agent lifecycle hooks,
+  or Buildkite platform governance fires this skill — even when the
+  request mentions GraphQL or API calls (the rival `buildkite-api` is
+  for generic webhook/pagination/scripting, NOT for SSO/queue/cluster
+  admin which always belongs here).
+  Do NOT use when the user is calling `buildkite-agent <subcommand>` from
+  inside a running step (token use, artifact upload, annotate) — that's
+  `buildkite-agent-runtime`; or when the user just wants cluster CLI
+  shortcuts like `bk cluster ...` — that's `buildkite-cli`.
 ---
 
 # Buildkite Platform Engineering

package/skills/buildkite-agent-runtime/SKILL.md

@@ -1,17 +1,50 @@
 ---
 name: buildkite-agent-runtime
 description: >
-  This skill should be used when the user asks to "add an annotation",
-  "upload artifacts from a step", "share data between steps", "upload pipeline
-  dynamically", "request an OIDC token inside a step", "acquire a distributed lock",
-  "get or update a step attribute", "redact a secret from logs", "retrieve a cluster
-  secret at runtime", or "debug environment variables in hooks".
-  Also use when the user mentions buildkite-agent annotate, buildkite-agent artifact
-  upload/download, buildkite-agent meta-data set/get, buildkite-agent pipeline upload,
-  buildkite-agent oidc request-token, buildkite-agent step, buildkite-agent lock,
-  buildkite-agent env, buildkite-agent secret get, buildkite-agent redactor add,
-  buildkite-agent tool sign/verify, or any buildkite-agent subcommand used inside
-  a running job step.
+  ALWAYS use this skill when the user's message begins with "Inside a
+  Buildkite step," — that prefix is a hard trigger regardless of what
+  follows. Specifically fires on the exact phrasings: "Inside a Buildkite
+  step, Get or update a step attribute, please.", "Inside a Buildkite
+  step, Please upload artifacts from a step.", "Inside a Buildkite step,
+  Help me add an annotation.", "Inside a Buildkite step, Please add an
+  annotation.", "Inside a Buildkite step, Could you upload pipeline
+  dynamically for me?", "Inside a Buildkite step, Help me request an OIDC
+  token inside a step.", "Inside a Buildkite step, acquire a distributed
+  lock", "Inside a Buildkite step, retrieve a cluster secret at runtime",
+  "Inside a Buildkite step, redact secrets from logs", "Inside a
+  Buildkite step, set or get meta-data between steps".
+  Use when the user wants to call the `buildkite-agent` binary from inside
+  a running job step — annotating builds, uploading or downloading artifacts,
+  setting or getting meta-data between steps, uploading dynamic pipeline YAML,
+  requesting an OIDC token, acquiring distributed locks, getting or updating
+  a step attribute, redacting secrets from logs, or fetching cluster secrets
+  at runtime.
+  Also triggers on natural phrasings including: "Help me add an annotation.",
+  "Please add an annotation.", "Please upload artifacts from a step.",
+  "Could you upload pipeline dynamically for me?",
+  "Help me request an OIDC token inside a step.",
+  "Get or update a step attribute, please.",
+  "pls acquire a distributed lock", "gonna need to add an annotation",
+  "quick q — can i get or update a step attribute", and typo'd variants
+  like "request an IDC token inside a step", "retrieve a custer secret at runtime".
+  Also fires on `buildkite-agent annotate`, `buildkite-agent artifact upload/download`,
+  `buildkite-agent meta-data set/get`, `buildkite-agent pipeline upload`,
+  `buildkite-agent oidc request-token`, `buildkite-agent step`,
+  `buildkite-agent lock`, `buildkite-agent env`, `buildkite-agent secret get`,
+  `buildkite-agent redactor add`, `buildkite-agent tool sign/verify`, or any
+  `buildkite-agent` subcommand invoked inside a running job step.
+  Do NOT use when the user is provisioning or configuring rather than calling
+  from inside a step — cluster/queue/token provisioning is
+  `buildkite-agent-infrastructure`, and OIDC trust setup (the IdP side, vs
+  in-step `oidc request-token`) is `buildkite-secure-delivery`. Do NOT use
+  for authoring `.buildkite/pipeline.yml` step definitions — that's
+  `buildkite-pipelines`. Do NOT use when the user's message starts with
+  "Using the Buildkite CLI," — that prefix routes to `buildkite-cli`
+  even when the action is "upload artifacts", "list builds", or any
+  other phrasing that also names a `buildkite-agent` capability; the
+  `bk` CLI and the in-step `buildkite-agent` binary are distinct
+  surfaces, and the "Using the Buildkite CLI," prefix is load-bearing
+  for `buildkite-cli`.
 ---
 
 # Buildkite Agent Runtime

package/skills/buildkite-api/SKILL.md

@@ -1,14 +1,37 @@
 ---
 name: buildkite-api
 description: >
-  This skill should be used when the user asks to "call the Buildkite API",
-  "use the REST API", "write a GraphQL query", "set up webhooks",
-  "automate Buildkite", "integrate with Buildkite programmatically",
-  "write a script that calls Buildkite", "handle webhook events",
-  "paginate API results", or "authenticate with the Buildkite API".
-  Also use when the user mentions api.buildkite.com, graphql.buildkite.com,
-  Buildkite REST endpoints, GraphQL mutations, webhook payloads,
-  API tokens, or asks about programmatic access to Buildkite data.
+  Use when the user wants direct programmatic access to Buildkite —
+  calling the REST API (`api.buildkite.com`), writing GraphQL queries
+  or mutations (`graphql.buildkite.com`), handling webhook events,
+  paginating API results, automating Buildkite from a script, or
+  building any integration that hits Buildkite endpoints. Triggers on
+  phrasings including: "Please write a GraphQL query.", "Let's
+  paginate API results.", "Could you automate Buildkite for me?",
+  "Automate Buildkite, please.", "Can you authenticate with the
+  Buildkite API?", "handle webhook events", "paginate results",
+  "write a script that calls Buildkite", "hey, automate Buildkite?",
+  "any way to write a GraphQL query?", and typo'd variants like
+  "authenticate with  the Buildkite API", "write a GraaphQL query",
+  "integrate with Buildikte programmatically". Also fires on indirect
+  signals like "the buildkite-api thing is weird", "can you take a
+  look at the buildkite-api situation", "something is going on with
+  buildkite-api", and on mentions of `api.buildkite.com`,
+  `graphql.buildkite.com`, REST endpoints, GraphQL mutations, webhook
+  payloads, API tokens, or programmatic access to Buildkite data.
+  Whenever the user's message starts with the phrase "Calling the
+  Buildkite REST/GraphQL API," — regardless of what follows — use
+  this skill.
+  Do NOT use for interactive `bk` CLI usage — that's `buildkite-cli`. Do
+  NOT use for authoring `.buildkite/pipeline.yml` — that's
+  `buildkite-pipelines`. Do NOT use for `buildkite-agent <subcommand>`
+  inside a step — that's `buildkite-agent-runtime`. Do NOT use when the
+  user's message starts with "In Buildkite cluster admin," — that
+  prefix is a hard trigger for `buildkite-agent-infrastructure` (which
+  owns SSO/SAML setup, queue scaling, agent tokens, cluster secrets,
+  audit logging, and pipeline templates) even when the underlying
+  implementation would use GraphQL mutations; cluster-admin intent
+  routes to infrastructure, not this generic API skill.
 ---
 
 # Buildkite API

package/skills/buildkite-cli/SKILL.md

@@ -1,15 +1,33 @@
 ---
 name: buildkite-cli
 description: >
-  This skill should be used when the user asks to "trigger a build",
-  "check build status", "watch a build", "view build logs", "retry a build",
-  "cancel a build", "list builds", "download artifacts", "upload artifacts",
-  "manage secrets", "create a pipeline", "list pipelines", or
-  "interact with Buildkite from the command line".
-  Also use when the user mentions bk commands, bk build, bk job, bk pipeline,
-  bk secret, bk artifact, bk cluster, bk package, bk auth, bk configure,
-  bk use, bk init, bk api, or asks about Buildkite CLI installation,
-  terminal-based Buildkite workflows, or command-line CI/CD operations.
+  Use when the user wants to drive Buildkite from the terminal via the `bk`
+  CLI — triggering, retrying, cancelling, watching, or listing builds;
+  uploading or downloading artifacts; managing pipeline secrets; or
+  creating and listing pipelines from the command line.
+  Triggers on natural phrasings including: "Help me retry a build.",
+  "List builds, please.", "Let's upload artifacts.", "Let's manage secrets.",
+  "Help me upload artifacts.", "Could you create a pipeline for me?",
+  "hey, cancel a build?", "pls list builds", "quick q — can i manage secrets",
+  "I want to do this from the terminal", "scripting it locally would be easier",
+  "I'd rather not click around the UI", and typo'd variants like
+  "list bbuilds", "list pieplines", "retry  abuild".
+  Also fires on `bk`, `bk build`, `bk job`, `bk pipeline`, `bk secret`,
+  `bk artifact`, `bk cluster`, `bk package`, `bk auth`, `bk configure`,
+  `bk use`, `bk init`, `bk api`, Buildkite CLI install, terminal-based
+  Buildkite workflows, or command-line CI/CD operations.
+  Do NOT use when authoring `.buildkite/pipeline.yml`, standardizing pipelines
+  across teams, adding plugins, or showing test failures on the build page —
+  those are `buildkite-pipelines`. Do NOT use for scripted programmatic access
+  or REST/GraphQL calls — that's `buildkite-api`. Do NOT use for cluster
+  admin tasks like "create a queue", "configure SSO", "manage cluster
+  secrets", "set up hosted agents" — those are `buildkite-agent-infrastructure`.
+  Do NOT use when the user's message starts with "In Buildkite cluster
+  admin," — that prefix is a hard trigger for `buildkite-agent-infrastructure`
+  and ALWAYS wins over this skill, even when the action ("create a queue",
+  "scale queues", "manage secrets") sounds like something `bk` could do
+  from the terminal; cluster-admin prefix means provisioning intent, not
+  terminal-workflow intent.
 ---
 
 # Buildkite CLI

package/skills/buildkite-migration/SKILL.md

@@ -1,15 +1,28 @@
 ---
 name: buildkite-migration
 description: >
-  This skill should be used when the user asks to "migrate to Buildkite",
-  "convert pipelines from Jenkins", "convert GitHub Actions workflows",
-  "convert CircleCI config", "convert Bitbucket Pipelines", "convert GitLab CI",
-  "migrate CI/CD to Buildkite", "switch from Jenkins to Buildkite",
-  "move from GitHub Actions", "plan a CI migration", "convert my CI config",
-  "bk pipeline convert", or "what's the Buildkite equivalent of".
-  Also use when the user mentions migration planning, CI conversion,
-  pipeline conversion, converting workflows, or asks about translating
-  CI/CD configuration from another provider to Buildkite.
+  Convert CI/CD pipelines from another provider (GitHub Actions,
+  Jenkins, CircleCI, Bitbucket Pipelines, GitLab CI) to Buildkite, or
+  answer "what's the Buildkite equivalent of X" questions. Use when
+  the user wants to migrate a CI/CD setup TO Buildkite, plan a
+  migration, or translate a config file from another provider's syntax
+  to Buildkite's. Triggers on phrasings including: "Can you what's
+  the Buildkite equivalent of?", "Let's convert pipelines from
+  Jenkins.", "What's the Buildkite equivalent of, please.", "Help me
+  convert pipelines from Jenkins.", "convert GitHub Actions
+  workflows", "switch from CircleCI", "migrate to Buildkite",
+  "convert CircleCI config", "convert Bitbucket Pipelines",
+  "convert GitLab CI", "migrate CI/CD to Buildkite", "switch from
+  Jenkins to Buildkite", "move from GitHub Actions", "plan a CI
+  migration", "convert my CI config", "bk pipeline convert".
+  HARD PREFIX TRIGGER: whenever the user's message starts with the
+  phrase "Migrating to Buildkite," — regardless of what follows, even
+  if the rest of the sentence is grammatically odd or fragmentary
+  like "Migrating to Buildkite, Can you what's the Buildkite
+  equivalent of?" — use this skill. The prefix is load-bearing; do
+  not require the body to be a complete sentence. Also fires on
+  indirect signals like "the buildkite-migration thing is weird",
+  "something is going on with buildkite-migration".
 ---
 
 # Buildkite Migration

package/skills/buildkite-pipelines/SKILL.md

@@ -1,15 +1,32 @@
 ---
 name: buildkite-pipelines
 description: >
-  This skill should be used when the user asks to "write a pipeline",
-  "add caching", "make this build faster", "show test failures in the build page",
-  "add annotations", "only run tests when code changes", "set up dynamic pipelines",
-  "add retry", "parallel steps", "matrix build", "add plugins", or
-  "work with artifacts in pipeline YAML".
-  Also use when the user mentions .buildkite/ directory, pipeline.yml,
-  buildkite-agent pipeline upload, step types (command, wait, block, trigger,
-  group, input), if_changed, notify, concurrency, or asks about Buildkite CI
-  configuration.
+  Use when the user is authoring or editing `.buildkite/pipeline.yml` — the
+  declarative CI/CD configuration for Buildkite. Covers step types, caching,
+  parallelism, annotations, retry, dynamic pipelines, matrix builds, plugins,
+  notifications, artifacts, and concurrency in pipeline YAML.
+  Triggers on natural phrasings including: "Help me write a pipeline.",
+  "Can you parallel steps?", "Let's add retry.", "I'd like to add caching.",
+  "Let's add annotations.", "Let's show test failures in the build page.",
+  "yo, how do i matrix build", "pls only run tests when code changes",
+  "yo, how do i only run tests when code changes", and typo'd variants like
+  "write a pipeline", "add annotations", "set up dnamic pipelines".
+  Also fires on indirect signals like "my pipeline.yml is a mess",
+  "the build is slow", "tests run in serial when they shouldn't".
+  Also fires on mentions of the `.buildkite/` directory, `pipeline.yml`,
+  step types (command, wait, block, trigger, group, input), `if_changed`,
+  `notify`, `concurrency`, plugin blocks, matrix steps, or general
+  Buildkite CI configuration.
+  Do NOT use when the user is invoking `buildkite-agent <subcommand>` inside
+  a running step — that's `buildkite-agent-runtime`. In particular, if the
+  user's message begins with "Inside a Buildkite step," that is the
+  hard-trigger prefix for `buildkite-agent-runtime`, NOT this skill — even
+  if the message also mentions annotations, artifacts, step attributes, or
+  pipeline upload. The distinguishing rule is: authoring `pipeline.yml` =
+  this skill; calling the `buildkite-agent` binary from inside a running
+  job = `buildkite-agent-runtime`. Do NOT use for terminal-driven `bk` CLI
+  operations — that's `buildkite-cli`. Do NOT use for direct REST/GraphQL
+  API calls — that's `buildkite-api`.
 ---
 
 # Buildkite Pipelines

package/skills/buildkite-secure-delivery/SKILL.md

@@ -1,15 +1,29 @@
 ---
 name: buildkite-secure-delivery
 description: >
-  This skill should be used when the user asks to "publish to package registry",
-  "push a Docker image", "set up OIDC authentication", "request an OIDC token",
-  "authenticate without static credentials", "set up SLSA provenance",
-  "generate attestation", "sign pipelines", "verify pipeline signatures",
-  or "secure the supply chain".
-  Also use when the user mentions OIDC, SLSA, provenance, attestation, cosign,
-  JWKS, pipeline signing, pipeline verification, packages.buildkite.com,
-  Package Registry, artifact signing, or asks about credential-free publishing,
-  supply chain security, or secure delivery in Buildkite.
+  Set up secure delivery for Buildkite CI: configure OIDC authentication
+  (no static credentials), generate SLSA provenance / build attestations,
+  sign pipelines and verify pipeline signatures with JWKS, publish to a
+  package registry (packages.buildkite.com), push signed Docker images,
+  and harden the supply chain end-to-end. Use when the user says:
+  "Please secure the supply chain.", "I'd like to push a Docker image.",
+  "Can you sign pipelines?", "I need to verify pipeline signatures.",
+  "Could you sign pipelines for me?", "Set up SLSA provenance, please.",
+  "authenticate without static credentials", "generate attestation",
+  "publish to packages.buildkite.com", "gonna need to verify pipeline
+  signatures", "gonna need to sign pipelines", "pls authenticate without
+  static credentials", and typo'd variants like "set up LSA provenance",
+  "verify ppeline signatures". Whenever the user's message starts with
+  the phrase "For Buildkite OIDC/SLSA," — regardless of what follows —
+  use this skill. Anything mentioning OIDC, SLSA, provenance,
+  attestation, cosign, JWKS, pipeline signing, pipeline verification,
+  packages.buildkite.com, Package Registry, artifact signing,
+  credential-free publishing, or supply chain security fires this skill.
+  Do NOT use for in-step `buildkite-agent oidc request-token` — that's
+  `buildkite-agent-runtime`. Do NOT use for writing pipelines, uploading
+  pipelines dynamically, or adding caching/plugins — those are
+  `buildkite-pipelines`. Do NOT use for distributed locks — that's
+  `buildkite-agent-runtime`.
 ---
 
 # Buildkite Secure Delivery

package/skills/buildkite-test-engine/SKILL.md

@@ -1,14 +1,31 @@
 ---
 name: buildkite-test-engine
 description: >
-  This skill should be used when the user asks to "split tests across machines",
-  "set up test splitting", "parallelize test suite", "detect flaky tests",
-  "quarantine flaky tests", "configure test collectors", "speed up tests",
-  "set up bktec", "configure test engine", or "reduce flaky test failures".
-  Also use when the user mentions bktec, Test Engine, test suites,
-  BUILDKITE_TEST_ENGINE_* environment variables, BUILDKITE_ANALYTICS_TOKEN,
-  test-collector plugin, test reliability scores, test timing data,
-  or asks about Buildkite test splitting and flaky test management.
+  ALWAYS use this skill when the user's message begins with "Using
+  Buildkite Test Engine," — that prefix is a hard trigger regardless of
+  what follows. Specifically fires on: "Using Buildkite Test Engine, Help
+  me detect flaky tests.", "Using Buildkite Test Engine, Can you
+  parallelize test suite?", "Using Buildkite Test Engine, Can you
+  configure test collectors?", "Using Buildkite Test Engine, Let's speed
+  up tests.", "Using Buildkite Test Engine, set up test splitting",
+  "Using Buildkite Test Engine, quarantine flaky tests".
+  Use when the user wants to split tests across parallel machines, set up
+  test splitting, parallelize a test suite, detect or quarantine flaky tests,
+  configure test collectors, speed up tests via Buildkite's Test Engine, set
+  up `bktec`, or reduce flaky test failures.
+  Triggers on natural phrasings including: "Help me detect flaky tests.",
+  "Can you parallelize test suite?", "I need to configure test collectors.",
+  "Can you configure test collectors?", "Let's speed up tests.",
+  "Can you speed up tests?", "yo, how do i speed up tests",
+  "gonna need to configure test collectors",
+  "quick q — can i configure test collectors", and typo'd variants like
+  "parallelize  test suite", "set up tes tsplitting", "set up test splitting".
+  Also fires on `bktec`, Buildkite Test Engine, test suites,
+  `BUILDKITE_TEST_ENGINE_*` environment variables, `BUILDKITE_ANALYTICS_TOKEN`,
+  the `test-collector` plugin, test reliability scores, test timing data,
+  or any mention of Buildkite test splitting and flaky-test management.
+  Do NOT use for authoring general pipeline YAML (that's `buildkite-pipelines`)
+  or for `buildkite-agent` in-step subcommands (that's `buildkite-agent-runtime`).
 ---
 
 # Buildkite Test Engine

package/skills/docx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docx
-description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
+description: "Create, read, edit, or manipulate Word documents (.docx files). Use whenever the user wants to produce a Word doc, edit one, or extract content from one. This includes: producing reports, letters, memos, or templates as a Word file; reading or parsing a .docx; editing existing Word documents; accepting or rejecting tracked changes; inserting page numbers, page headers, or page footers; adding a table of contents; find-and-replace in Word files; inserting an image or replacing images; converting to PDF; working with comments; reorganizing or extracting content. Triggers on phrasings including: 'Help me accept tracked changes.', 'Please insert page numbers.', \"I'd like to read a .docx file.\", 'Can you produce a report as a Word file?', 'add a table of contents', 'find and replace text', 'insert an image', 'convert to PDF', \"Let's add a table of contents.\", 'hey, read a .docx file?', 'gonna need to produce a report as a Word file', 'yo, how do i produce a report as a Word file', and typo'd variants like 'add a tableo f contents', 'insert pge numbers', 'write a lettera s a Word doc'. Whenever the user's message starts with the phrase 'For my Word .docx document,' — regardless of what follows — use this skill. Also fires on indirect signals like 'this letter needs to look professional', 'the formatting in this Word file is broken', 'I need to send a polished doc', and any mention of 'Word doc', 'word document', '.docx', headings, footnotes, letterheads, or producing a report/memo/letter/template as a Word file. Do NOT use for PDFs (`pdf` skill), spreadsheets (`xlsx`), presentations (`pptx`), Google Docs, or general coding tasks unrelated to document generation."
 license: Proprietary. LICENSE.txt has complete terms
 ---