slackapi · WilliamBergamin · Jul 16, 2026 · Jul 14, 2026 · Jul 14, 2026 · Jul 16, 2026
@@ -2,4 +2,4 @@
 
 This directory contains [**Changesets**](https://github.com/changesets/changesets) which are markdown files that describe package changes for the next release.
 
-For guidance on when and how to add changesets, checkout the [Maintainer's Guide](../.github/maintainers_guide.md#-updating-changesets).
+For guidance on when and how to add changesets, checkout the [Maintainer's Guide](../.github/maintainers_guide.md#updating-changesets).
@@ -8,4 +8,4 @@ Our goal is to maintain a safe, helpful and friendly community for everyone, reg
 
 This code and related procedures also apply to unacceptable behavior occurring outside the scope of community activities, in all community venues (online and in-person) as well as in all one-on-one communications, and anywhere such behavior has the potential to adversely affect the safety and well-being of community members.
 
-For more information on our code of conduct, please visit [https://slackhq.github.io/code-of-conduct](https://slackhq.github.io/code-of-conduct)
+For more information on our code of conduct, please visit [https://slackhq.github.io/code-of-conduct](https://slackhq.github.io/code-of-conduct)
@@ -6,27 +6,30 @@ well.
 
 There are many ways you can contribute! :heart:
 
-### Bug Reports and Fixes :bug:
--  If you find a bug, please search for it in the [Issues](https://github.com/slackapi/slack-skills-plugin/issues), and if it isn't already tracked,
-   [create a new issue](https://github.com/slackapi/slack-skills-plugin/issues/new). Fill out the "Bug Report" section of the issue template. Even if an Issue is closed, feel free to comment and add details, it will still
-   be reviewed.
--  Issues that have already been identified as a bug (note: able to reproduce) will be labelled `bug`.
--  If you'd like to submit a fix for a bug, [send a Pull Request](#creating_a_pull_request) and mention the Issue number.
-  -  Include tests that isolate the bug and verifies that it was fixed.
-
-### New Features :bulb:
--  If you'd like to add new functionality to this project, describe the problem you want to solve in a [new Issue](https://github.com/slackapi/slack-skills-plugin/issues/new).
--  Issues that have been identified as a feature request will be labelled `enhancement`.
--  If you'd like to implement the new feature, please wait for feedback from the project
-   maintainers before spending too much time writing the code. In some cases, `enhancement`s may
-   not align well with the project objectives at the time.
-
-### Tests :mag:, Documentation :books:, Miscellaneous :sparkles:
--  If you'd like to improve the tests, you want to make the documentation clearer, you have an
-   alternative implementation of something that may have advantages over the way its currently
-   done, or you have any other change, we would be happy to hear about it!
-  -  If its a trivial change, go ahead and [send a Pull Request](#creating_a_pull_request) with the changes you have in mind.
-  -  If not, [open an Issue](https://github.com/slackapi/slack-skills-plugin/issues/new) to discuss the idea first.
+## Bug Reports and Fixes :bug
+
+- If you find a bug, please search for it in the [Issues](https://github.com/slackapi/slack-skills-plugin/issues), and if it isn't already tracked,
+  [create a new issue](https://github.com/slackapi/slack-skills-plugin/issues/new). Fill out the "Bug Report" section of the issue template. Even if an Issue is closed, feel free to comment and add details, it will still
+  be reviewed.
+- Issues that have already been identified as a bug (note: able to reproduce) will be labelled `bug`.
+- If you'd like to submit a fix for a bug, [send a Pull Request](#creating-a-pull-request) and mention the Issue number.
+  - Include tests that isolate the bug and verifies that it was fixed.
+
+### New Features :bulb
+
+- If you'd like to add new functionality to this project, describe the problem you want to solve in a [new Issue](https://github.com/slackapi/slack-skills-plugin/issues/new).
+- Issues that have been identified as a feature request will be labelled `enhancement`.
+- If you'd like to implement the new feature, please wait for feedback from the project
+  maintainers before spending too much time writing the code. In some cases, `enhancement`s may
+  not align well with the project objectives at the time.
+
+### Tests :mag:, Documentation :books:, Miscellaneous :sparkles
+
+- If you'd like to improve the tests, you want to make the documentation clearer, you have an
+  alternative implementation of something that may have advantages over the way its currently
+  done, or you have any other change, we would be happy to hear about it!
+  - If its a trivial change, go ahead and [send a Pull Request](#creating-a-pull-request) with the changes you have in mind.
+  - If not, [open an Issue](https://github.com/slackapi/slack-skills-plugin/issues/new) to discuss the idea first.
 
 If you're new to our project and looking for some way to make your first contribution, look for
 Issues labelled `good first contribution`.
@@ -39,22 +42,22 @@ For your contribution to be accepted:
 - [x] The test suite must be complete and pass.
 - [x] The changes must be approved by code review.
 - [x] Commits should be atomic and messages must be descriptive. Related issues should be mentioned by Issue number.
-- [x] User-facing changes include a changeset (run `npx changeset add`). See [Updating Changesets](./maintainers_guide.md#-updating-changesets) for the format; releases are automated from these.
+- [x] User-facing changes include a changeset (run `npx changeset add`). See [Updating Changesets](./maintainers_guide.md#updating-changesets) for the format; releases are automated from these.
 
 If the contribution doesn't meet the above criteria, you may fail our automated checks or a maintainer will discuss it with you. You can continue to improve a Pull Request by adding commits to the branch from which the PR was created.
 
 [Interested in knowing more about about pull requests at Slack?](https://slack.engineering/on-empathy-pull-requests-979e4257d158#.awxtvmb2z)
 
 ## Creating a Pull Request
 
-1.  :fork_and_knife: Fork the repository on GitHub.
-2.  :runner: Clone/fetch your fork to your local development machine. It's a good idea to run the tests just
-    to make sure everything is in order.
-3.  :herb: Create a new branch and check it out.
-4.  :crystal_ball: Make your changes and commit them locally. Magic happens here!
-5.  :arrow_heading_up: Push your new branch to your fork. (e.g. `git push username fix-issue-16`).
-6.  :inbox_tray: Open a Pull Request on github.com from your new branch on your fork to `main` in this
-    repository.
+1. :fork_and_knife: Fork the repository on GitHub.
+2. :runner: Clone/fetch your fork to your local development machine. It's a good idea to run the tests just
+   to make sure everything is in order.
+3. :herb: Create a new branch and check it out.
+4. :crystal_ball: Make your changes and commit them locally. Magic happens here!
+5. :arrow_heading_up: Push your new branch to your fork. (e.g. `git push username fix-issue-16`).
+6. :inbox_tray: Open a Pull Request on github.com from your new branch on your fork to `main` in this
+   repository.
 
 ## Maintainers
 

@@ -31,10 +31,10 @@ brew install pyenv
 Install necessary Python runtime for development/testing.
 
 ```sh
-$ pyenv install 3.14 # select the latest patch version
-$ pyenv local 3.14
+pyenv install 3.14 # select the latest patch version
+pyenv local 3.14
 
-$ pyenv rehash
+pyenv rehash
 ```
 
 Then, you can create a new Virtual Environment this way:
@@ -62,7 +62,7 @@ make install
 ```
 
 The tests read configuration from environment variables. Copy the example file
-and fill in what you need — each variable is documented inline, and the
+and fill in what you need. Each variable is documented inline, and the
 `Makefile` auto-loads `.env`:
 
 ```sh
@@ -73,11 +73,15 @@ vim .env
 
 ### Running the tests
 
-Always use the `make` targets — never invoke `pytest`, `ruff`, or `python`
+Always use the `make` targets, never invoke `pytest`, `ruff`, `python`, or other tools
 directly. The targets manage the virtualenv, load `.env`, and set up the test
 dependencies for you.
 
+Run `make help` to list every target with its description (read straight from the
+`Makefile`, so it's always current). The ones you'll reach for most:
+
 ```sh
+make help        # list all targets with their descriptions
 make test-unit   # fast structural + frontmatter checks (this is what CI runs)
 make test-eval   # LLM-judged skill evaluations (local only)
 make test        # both
@@ -87,10 +91,12 @@ make typecheck   # Mypy static type checks
 ```
 
 Markdown linting is powered by [rumdl](https://github.com/rvben/rumdl), a
-markdownlint-compatible Rust linter. It validates `skills/`, `commands/`,
-`README.md`, and `AGENTS.md`. Rules and disabled checks are configured under
-`[tool.rumdl]` in `pyproject.toml` — tune that section when a new skill trips a
-rule that isn't worth enforcing.
+markdownlint-compatible Rust linter. It validates the plugin's authored
+markdown — `skills/`, `commands/`, `README.md`, `AGENTS.md`, and the
+contributor-facing `.github/` docs. Rules, disabled checks, and the `include`
+list of linted files are configured under `[tool.rumdl]` in `pyproject.toml`;
+tune that section when a new file or skill trips a rule that isn't worth
+enforcing.
 
 ### Testing in Claude Code
 
@@ -101,7 +107,7 @@ Load your local changes into Claude Code for a single session with the
 claude --plugin-dir ./
 ```
 
-This loads the `slack` plugin from your checkout — its skills and commands, and
+This loads the `slack` plugin from your checkout: its skills and commands, and
 the HTTP MCP server from `.mcp.json`. If you already have the published
 `slack` plugin installed, the local copy takes precedence **for that session
 only**: nothing is written to your settings, and the installed version is
@@ -134,7 +140,7 @@ uninstall, in addition to removing the virtualenv and other generated files.)
 
 Follow the [conventional commit specification][conv-commits]. PR titles and commit messages use prefixes like `feat:`, `fix:`, `chore:`, `docs:`, etc. First letter after the prefix is lowercase unless it's a proper noun.
 
-### 🎁 Updating Changesets
+### Updating Changesets
 
 This project uses [Changesets](https://github.com/changesets/changesets) to track changes and automate releases.
 
@@ -160,7 +166,7 @@ Updates to documentation, tests, or CI might not require new entries.
 
 When a PR containing changesets is merged to `main`, a different PR is opened or updated using [changesets/action](https://github.com/changesets/action) which consumes the pending changesets, bumps the package version, and updates the `CHANGELOG` in preparation to release.
 
-### 🚀 Releases
+### Releases
 
 Releasing can feel intimidating at first, but don't fret! Venture on!
 
@@ -180,8 +186,7 @@ New official package versions are published when the release PR created from cha
 
 ### CODEOWNERS
 
-All files are owned by `@slackapi/platform-devxp`. Any PR to this repo will
-automatically request review from this team.
+Owners are defined in [`.github/CODEOWNERS`](CODEOWNERS). Any PR to this repo automatically requests review from this team.
 
 ### Dependabot
 
@@ -196,14 +201,14 @@ Patch and minor updates are auto-approved and auto-merged via the
 - Feature requests for new skills should be discussed in the issue before
   implementation begins.
 - Labels:
-  - `bug` — confirmed defects
-  - `enhancement` — feature requests and new functionality
-  - `docs` — documentation-only changes
-  - `test` — test-only changes
-  - `build` — CI, GitHub Actions, and build/compilation processes
-  - `chore` — repo structure, required files, release scaffolding, general maintenance
-  - `dependencies` — dependency updates (Dependabot applies this automatically)
-  - `security` — vulnerability fixes, hardening, and security audit findings
+  - `bug`: confirmed defects
+  - `enhancement`: feature requests and new functionality
+  - `docs`: documentation-only changes
+  - `test`: test-only changes
+  - `build`: CI, GitHub Actions, and build/compilation processes
+  - `chore`: repo structure, required files, release scaffolding, general maintenance
+  - `dependencies`: dependency updates (Dependabot applies this automatically)
+  - `security`: vulnerability fixes, hardening, and security audit findings
     (apply alongside `bug`/`build`/`dependencies` as appropriate)
 
 ---

@@ -1,18 +1,18 @@
 ### Summary
 
-(Please describe the goal of this pull request and mention any related issue numbers)
+<!-- Please describe the goal of this pull request and mention any related issue numbers -->
 
 ### Preview
 
-(Add screenshots, GIFs, or recordings that show the changes)
+<!-- Add screenshots, GIFs, or recordings that show the changes -->
 
 ### Testing
 
-(List the steps used to verify these changes)
+<!-- List the steps used to verify these changes -->
 
 ### Notes
 
-(Add any additional context, trade-offs, or follow-up items)
+<!-- Add any additional context, trade-offs, or follow-up items -->
 
 ### Requirements
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@

		This directory contains [Changesets](https://github.com/changesets/changesets) which are markdown files that describe package changes for the next release.

		For guidance on when and how to add changesets, checkout the [Maintainer's Guide](../.github/maintainers_guide.md#-updating-changesets).
		For guidance on when and how to add changesets, checkout the [Maintainer's Guide](../.github/maintainers_guide.md#updating-changesets).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,4 +8,4 @@ Our goal is to maintain a safe, helpful and friendly community for everyone, reg

		This code and related procedures also apply to unacceptable behavior occurring outside the scope of community activities, in all community venues (online and in-person) as well as in all one-on-one communications, and anywhere such behavior has the potential to adversely affect the safety and well-being of community members.

		For more information on our code of conduct, please visit [https://slackhq.github.io/code-of-conduct](https://slackhq.github.io/code-of-conduct)
		For more information on our code of conduct, please visit [https://slackhq.github.io/code-of-conduct](https://slackhq.github.io/code-of-conduct)