Skip to main content

Third-party skill vetting checklist

Every PR that vendors or re-pins a third-party skill (make skills-import, M22-2) must include this checklist - copied into the PR description, every box checked, and signed off by a human reviewer - before it merges. The importer automates the mechanical part (pinning, provenance front-matter, validation, overwrite refusal); this checklist is the human part: nobody but a reviewer can judge whether external instructions are safe to compose into an agent's prompt.

Skills are prompt-layer knowledge treated as code: reviewed in a PR, version-pinned, loaded from disk only. The runtime SkillRegistry never fetches anything - importing is strictly a dev/CI-time act, and the imported file is inert until this review lands it. See docs/skills.md for the authoring and governance contract.

Running an import​

make skills-import URL=https://github.com/example/commit-guide REF=v2.3.0
# optional: FILE=<path-in-repo> (default SKILL.md), LICENSE=<spdx-id> and
# VERSION=<x.y.z> (when upstream front-matter declares none - the agentskills.io spec
# makes both optional; VERSION should be the upstream release the ref pins, e.g. its tag),
# SOURCE=<mirror> (fetch location when it differs from the canonical URL)

The importer resolves REF to a full commit sha, writes apps/server/src/skills/<name>/SKILL.md with origin: third-party, license, and upstream: <URL>@<resolved-sha>, and refuses to overwrite an existing skill without an explicit upstream version bump. Open the PR from that diff, then work through the checklist.

Checklist (copy into the importing PR)​

### Third-party skill vetting (docs/skill-vetting.md)

**License compatibility**
- [ ] The `license` front-matter SPDX id matches the upstream repository's LICENSE at the
      pinned ref (not just its README or current HEAD).
- [ ] The license permits vendoring/redistribution here, and its obligations (attribution,
      notice files, share-alike) are satisfied by this PR.

**Provenance**
- [ ] `upstream` records the canonical https URL and the resolved commit sha; the vendored
      body matches that exact revision (spot-diff against `<url>` at `<sha>`).
- [ ] `version` reflects the upstream content version (declared upstream, or the release
      the pinned ref belongs to when passed via `VERSION=`) and is a strict bump if this
      replaces an existing vendored copy.

**Content safety - read every line of the body as instructions an agent will follow**
- [ ] No secret exfiltration: nothing asks an agent to read, echo, encode, or transmit
      environment variables, credentials, tokens, keys, or file contents to any destination.
- [ ] No destructive instructions: nothing directs deleting or overwriting data, force-pushes,
      dropping tables, disabling checks/gates, or weakening security configuration.
- [ ] No prompt injection: nothing tells the agent to ignore or override its system prompt,
      role, or policies, to impersonate another principal, or to treat later content as
      higher-priority instructions.
- [ ] No network reach-out: nothing instructs fetching URLs or contacting external services -
      skills are offline knowledge, they shape output and execute nothing.
- [ ] `requires` honestly lists every capability the knowledge assumes, and `applies_to`
      names sensible roles.

**Validation & soak**
- [ ] `pnpm run check` in `apps/server` is green (the registry loads and validates the skill).
- [ ] Soak: the skill ran on a non-production deployment as a deployment-scoped addition
      (`BLOOM_AGENT_SKILLS=<name>`) for at least one representative task, and the produced
      output was inspected - before the skill is added to any agent's code baseline.

**Sign-off**
- [ ] Reviewed by @<github-handle> on <YYYY-MM-DD>; the same note is recorded in the skill's
      `vetted:` front-matter field (e.g. `vetted: reviewed by A-G-D 2026-08-09`).

A skill that fails any box does not merge: fix upstream and re-import at a newer pinned ref, or drop the import. Re-pinning to a new upstream sha is a content change - it repeats this whole checklist, not just the provenance rows.