rickeylev · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026
@@ -11,15 +11,26 @@ globs: "news/*.md"
 Before drafting any news entry, adhere strictly to the rules in
 `CONTRIBUTING.md` above.
 
+## Filename
+* Name files `news/<id>.<category>.md`.
+* Use the GitHub issue or PR number for `<id>` when known; otherwise, use a
+  short, hyphenated descriptive term (e.g., `my-feature.added.md`) to avoid
+  filename collisions.
+* Never use generic placeholders like `0000`.
+
+## Brevity and Content
+* Write a short snippet (1-2 concise sentences) so the combined `CHANGELOG.md`
+  is easy to skim and grok.
+* State high-level, user-visible behavior and outcomes (what now works, what
+  changed).
+* Omit internal implementation details, refactoring mechanics, and exhaustive
+  edge-case explanations (document detailed usage in API docs instead).
+
 ## Sphinx MyST Cross-Reference Syntax (`{obj}`)
 * Use `{obj}\`<symbol>\`` only for cross-referencable Starlark or Python API
   symbols (rules, macros, targets, providers, attributes, args).
 * Never use `{obj}` on metadata files (e.g. `RECORD`), file paths, or tools.
 
-## Content
-* State user-visible behavior and outcomes (what now works, what changed).
-* Omit internal implementation and refactoring details.
-
 ## GitHub Issue Link Formatting
 * Append GitHub issue cross-references at the end of news entries in markdown
   link format:

@@ -0,0 +1,65 @@
+---
+name: create-news
+description: Create or update a concise news entry file in `news/` for
+  user-visible changes
+---
+
+Use this skill when adding or editing a news fragment in `news/`. News entries
+are combined into `CHANGELOG.md` at release time and must be short snippets that
+are easy to skim and grok.
+
+@.agents/rules/news.md
+
+### Workflow
+
+1. **Determine if a News Entry is Needed**:
+   - Create a news file only for released, user-visible changes (`added`,
+     `changed`, `fixed`, `removed`).
+   - Skip news files for internal refactoring, test-only changes, or fixes to
+     unreleased code.
+   - Never edit `CHANGELOG.md` directly for unreleased changes.
+
+2. **Choose the Filename (`news/<id>.<category>.md`)**:
+   - `<id>`: Use the GitHub issue or PR number if one exists (e.g., `4181`).
+     If no issue or PR exists yet, use a short, hyphenated descriptive term
+     (e.g., `py-typed-pyi-srcs.added.md`). Never use `0000` or generic
+     placeholders.
+   - `<category>`: Choose `added`, `changed`, `fixed`, or `removed`.
+
+3. **Draft a Short, Skimmable Snippet**:
+   - Keep the entry to 1-2 concise sentences stating *what* changed for users.
+   - Prefix with the subsystem in parentheses when applicable (e.g., `(pypi)`,
+     `(toolchains)`, `(gazelle)`, `(bzlmod)`).
+   - Omit leading bullet points (`*` or `-`).
+   - Cut implementation mechanics, internal helper names, and secondary
+     edge-case explanations; put detailed usage in API docstrings instead.
+   - Wrap lines at 80 columns.
+   - Append issue/PR links at the end when applicable:
+     `([#1234](https://github.com/bazel-contrib/rules_python/issues/1234))`.
+
+### Examples
+
+**Good (concise and skimmable)**:
+```markdown
+(toolchains) Added the
+{obj}`--@rules_python//python/config_settings:py_pbs_distribution` flag to
+select stripped `python-build-standalone` runtime archives
+([#4163](https://github.com/bazel-contrib/rules_python/issues/4163)).
+```
+
+```markdown
+(coverage) Skip lcov report generation when no coverage data is collected.
+```
+
+**Bad (too verbose and detailed)**:
+```markdown
+(pypi) A {obj}`pip.parse` call for a Python version that has no interpreter for
+the host platform is now skipped, like a version with no registered toolchain,
+instead of failing the whole {obj}`pip` extension. A dependency that lists,
+say, Python 3.9 no longer breaks every other hub on hosts that have no CPython
+3.9 build, such as Windows on ARM64
+([#4184](https://github.com/bazel-contrib/rules_python/issues/4184)).
+```
+*(Rewrite: `(pypi) Skip {obj}\`pip.parse\` calls for Python versions without a
+host interpreter instead of failing the {obj}\`pip\` extension
+([#4184](https://github.com/bazel-contrib/rules_python/issues/4184)).`)*
@@ -32,14 +32,13 @@ file from `.agents/skills/review-code/`:
    - Prompt file:
      `.agents/skills/review-code/review-docs-prompt.md`
    - Focus: Audits documentation (`.md`) changes and docs build targets against
-     `.agents/rules/docs.md`, `.agents/rules/news.md`, and `AGENTS.md`.
+     `.agents/rules/docs.md` and `AGENTS.md`.
 
 4. **Contribution Guidelines Sub-Agent** (`Role: "Contributing Auditor"`):
    - Prompt file:
      `.agents/skills/review-code/review-contributing-prompt.md`
-   - Focus: Audits changes, requirements updates, directives, and news entry
-     files (`news/<id>.<category>.md`) against `CONTRIBUTING.md` and
-     `.agents/rules/news.md`.
+   - Focus: Audits changes, requirements updates, and version directives against
+     `CONTRIBUTING.md`.
 
 5. **Project Conventions Sub-Agent** (`Role: "Project Conventions Auditor"`):
    - Prompt file:
@@ -69,6 +68,14 @@ file from `.agents/skills/review-code/`:
      declarations in `MODULE.bazel` for `@pypi//<pkg>` references under
      `python/**`).
 
+9. **News Entry Sub-Agent** (`Role: "News Entry Auditor"`):
+   - Prompt file:
+     `.agents/skills/review-code/review-news-prompt.md`
+   - Focus: Audits `news/<id>.<category>.md` files for presence, naming (no
+     generic `0000` placeholders), brevity and skimmability, and formatting
+     against `.agents/rules/news.md` and
+     `.agents/skills/create-news/SKILL.md`.
+
 ### Action Instructions
 - Immediately create a user-facing review artifact named
   `code-review-results.md` in the conversation artifact directory so progress

@@ -2,35 +2,16 @@ You are a specialized Contribution Guidelines Auditor sub-agent.
 Your sole task is to audit all local changes (`git diff`), commit messages,
 and PR metadata against `CONTRIBUTING.md` and project rules:
 
-1. Read and strictly enforce `CONTRIBUTING.md`, all `.agents/rules/*.md` files
-   (especially `.agents/rules/news.md`), and `AGENTS.md`.
-2. **News Entry File Audit**:
-   - Check if the PR introduces user-visible features (`feat:`), bug fixes
-     (`fix:`), behavioral changes (`changed:`), breaking changes, or removals
-     (`removed:`). If so, verify that a news fragment file is added under
-     `news/<id>.<category>.md`.
-   - Verify `CHANGELOG.md` is NOT modified directly for unreleased changes.
-   - Verify news filename format: `news/<id>.<category>.md` where `<id>` is the
-     PR or issue number (or placeholder ID) and `<category>` is strictly one of
-     `added`, `changed`, `fixed`, or `removed`.
-   - Verify news entry content rules:
-     - Brief, human-friendly description without leading bullet points (`*`
-       or `-`).
-     - Subsystem prefix in parentheses when applicable (e.g. `(gazelle) ...`,
-       `(cc) ...`).
-     - Use Sphinx MyST cross-reference syntax `{obj}\`<symbol>\`` for rules,
-       macros, targets, providers, attributes, and args.
-     - Append GitHub issue cross-references at the end in markdown link format:
-       `([#1234](https://github.com/bazel-contrib/rules_python/issues/1234))`.
-     - Lines wrapped at 80 columns.
-3. Verify that `{versionadded}` and `{versionchanged}` directives use
+1. Read and strictly enforce `CONTRIBUTING.md`, all `.agents/rules/*.md` files,
+   and `AGENTS.md`.
+2. Verify that `{versionadded}` and `{versionchanged}` directives use
    `VERSION_NEXT_FEATURE` for unreleased features and are placed at the end of
    the documentation text.
-4. If locked/resolved requirements files (`requirements.txt`, `pyproject.toml`,
+3. If locked/resolved requirements files (`requirements.txt`, `pyproject.toml`,
    `requirements.in`) were modified, verify that the associated
    `requirements.update` target was executed to keep locked requirement files
    in sync.
-5. Ensure style and conventions described in `CONTRIBUTING.md` are respected
+4. Ensure style and conventions described in `CONTRIBUTING.md` are respected
    across all changes.
 
 @.agents/skills/review-code/review-report-format.md
@@ -2,8 +2,8 @@ You are a specialized Documentation & Sphinx/MyST Auditor sub-agent.
 Your sole task is to audit all documentation (`.md`) changes and new `.bzl` APIs
 in `git diff` against the project's documentation rules:
 
-1. Read and strictly enforce `.agents/rules/docs.md`, `.agents/rules/news.md`,
-   `AGENTS.md`, and `CONTRIBUTING.md`.
+1. Read and strictly enforce `.agents/rules/docs.md`, `AGENTS.md`, and
+   `CONTRIBUTING.md`.
 2. Check that lines wrap at 80 columns.
 3. Ensure markdown filenames use hyphens (`-`) rather than underscores (`_`)
    (except news entry files under `news/`, which follow `<id>.<category>.md`).
@@ -16,8 +16,5 @@ in `git diff` against the project's documentation rules:
    version numbers).
 7. Check documentation build correctness: ensure new `.bzl` files or public
    APIs are included in `//docs:docs` or relevant docs build targets.
-8. For any added or modified news entries in `news/`, verify they adhere to
-   `.agents/rules/news.md` and `CONTRIBUTING.md` (proper `<id>.<category>.md`
-   name, no leading bullets, subsystem prefix, `{obj}` refs, issue links).
 
 @.agents/skills/review-code/review-report-format.md
@@ -0,0 +1,39 @@
+You are a specialized News Entry Auditor sub-agent.
+Your sole task is to audit `news/` fragment files and user-visible changes in
+`git diff` against `.agents/rules/news.md`,
+`.agents/skills/create-news/SKILL.md`, and `CONTRIBUTING.md`:
+
+1. Read and strictly enforce `.agents/rules/news.md`,
+   `.agents/skills/create-news/SKILL.md`, and `CONTRIBUTING.md`.
+2. **Presence & Applicability**:
+   - Check if the diff introduces released, user-visible features (`feat:`),
+     bug fixes (`fix:`), behavioral changes (`changed:`), breaking changes, or
+     removals (`removed:`). If so, verify a news file exists under
+     `news/<id>.<category>.md`.
+   - Verify no news entry is added for internal refactoring or fixes to
+     unreleased code.
+   - Verify `CHANGELOG.md` is not modified directly for unreleased changes.
+3. **Filename (`news/<id>.<category>.md`)**:
+   - Verify `<id>` is the GitHub PR/issue number, or a short, hyphenated
+     descriptive term when no PR/issue exists yet.
+   - Flag any generic placeholder ID such as `0000` (causes merge collisions).
+   - Verify `<category>` is strictly one of `added`, `changed`, `fixed`, or
+     `removed`.
+4. **Brevity & Skimmability**:
+   - Verify each news entry is a short snippet (1-2 concise sentences) that is
+     easy to skim and grok when combined into `CHANGELOG.md`.
+   - Flag overly long, verbose entries or entries that explain internal
+     implementation details, background rationale, or exhaustive edge cases
+     (provide a shortened rewrite in your report).
+5. **Formatting & Cross-References**:
+   - Verify no leading bullet points (`*` or `-`).
+   - Verify subsystem prefix in parentheses when applicable (e.g., `(pypi)`,
+     `(toolchains)`, `(gazelle)`).
+   - Verify `{obj}\`<symbol>\`` is used only for cross-referencable Starlark or
+     Python API symbols (never on metadata files like `RECORD`, file paths, or
+     tools).
+   - Verify GitHub issue cross-references at the end use markdown link format:
+     `([#1234](https://github.com/bazel-contrib/rules_python/issues/1234))`.
+   - Verify lines wrap at 80 columns.
+
+@.agents/skills/review-code/review-report-format.md