diff --git a/.changeset/gray-anaconda-readme.md b/.changeset/gray-anaconda-readme.md
new file mode 100644
index 0000000..bd2b84e
--- /dev/null
+++ b/.changeset/gray-anaconda-readme.md
@@ -0,0 +1,5 @@
+---
+'@bomb.sh/tools': patch
+---
+
+Updates the README to document the `bsh sync` and `bsh publint` commands and accurately describe how `sync` links agent skills into a project
diff --git a/README.md b/README.md
index 2b0e35e..4096fd2 100644
--- a/README.md
+++ b/README.md
@@ -4,14 +4,16 @@ This package is an internal CLI intended to standardize tooling across all Bombs
 
 If you'd like to use this package for your own projects, please consider forking. We are not accepting issues on this repo.
 
-- `init` command for scaffolding new projects, which clones [our `template` repo](https://github.com/bombshell-dev/template)
+- `bsh init` command for scaffolding new projects, which clones [our `template` repo](https://github.com/bombshell-dev/template)
 - `bsh dev` command, using `node --experimental-transform-types --watch-path=./src/`
 - `bsh build` command, using [`tsdown`](https://tsdown.dev/) (ESM, unbundled)
 - `bsh test` command, using [`vitest`](https://vitest.dev/)
 - `bsh format` command, using [`oxfmt`](https://oxc.rs/docs/guide/usage/formatter)
-- `bsh lint` command, using [`oxlint`](https://oxc.rs/docs/guide/usage/linter), [`publint`](https://publint.dev/), [`knip`](https://knip.dev), [`tsgo`](https://npmx.dev/@typescript/native-preview)
+- `bsh lint` command, using [`oxlint`](https://oxc.rs/docs/guide/usage/linter), [`knip`](https://knip.dev), [`tsgo`](https://npmx.dev/@typescript/native-preview)
+- `bsh publint` command, using [`publint`](https://publint.dev/)
+- `bsh sync` command, which links our shared [agent skills](#agent-skills) into your project
 - shared `tsconfig.json` file
 
 ## Agent Skills
 
-If you use an AI coding agent, run `pnpm bsh sync` to copy skill files into your project's `skills/` directory. Claude Code users: add `@AGENTS.md` to your project's `CLAUDE.md`.
+If you use an AI coding agent, run `pnpm bsh sync` to symlink this package's skill files into your project's `skills/` directory. Synced skills are automatically added to your `.gitignore`, and an index of them is maintained in your `AGENTS.md`. Claude Code users: add `@AGENTS.md` to your project's `CLAUDE.md`.