chore(skills): rewrite skill descriptions in plain language - #2701
Open
alexeyv wants to merge 2 commits into
Open
chore(skills): rewrite skill descriptions in plain language#2701alexeyv wants to merge 2 commits into
alexeyv wants to merge 2 commits into
Conversation
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your trial has ended. Reactivate Greptile to resume code reviews.
📝 WalkthroughWalkthroughThe change updates 19 skill and module descriptions. The descriptions now specify workflow actions, supported inputs, generated outputs, and review behavior. No public entity declarations change. ChangesSkill metadata updates
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/bmm-skills/plan/bmad-project-context/SKILL.md`:
- Line 3: Restore terminal punctuation in the description at
src/bmm-skills/plan/bmad-project-context/SKILL.md:3-3 by appending a period
after “making”; apply the same punctuation-only update at
src/bmm-skills/plan/bmad-sprint-planning/SKILL.md:3-3 after “fix sprint status”
and at src/bmm-skills/plan/bmad-ux/SKILL.md:3-3 after “help me plan the UX”.
In `@src/bmm-skills/ship/bmad-code-review/SKILL.md`:
- Line 3: Add terminal periods to the descriptions on line 3 of both
src/bmm-skills/ship/bmad-code-review/SKILL.md and
src/bmm-skills/ship/bmad-qa-generate-e2e-tests/SKILL.md, placing each period
before the closing single quote.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 23ff39f3-a5db-4bb6-8f34-05f5de17a532
⛔ Files ignored due to path filters (2)
src/bmm-skills/module-help.csvis excluded by!**/*.csvsrc/core-skills/module-help.csvis excluded by!**/*.csv
📒 Files selected for processing (19)
src/bmm-skills/agents/bmad-agent-analyst/SKILL.mdsrc/bmm-skills/agents/bmad-agent-dev/SKILL.mdsrc/bmm-skills/module.yamlsrc/bmm-skills/plan/bmad-architecture/SKILL.mdsrc/bmm-skills/plan/bmad-prfaq/SKILL.mdsrc/bmm-skills/plan/bmad-prfaq/bmad-manifest.jsonsrc/bmm-skills/plan/bmad-project-context/SKILL.mdsrc/bmm-skills/plan/bmad-spec/SKILL.mdsrc/bmm-skills/plan/bmad-sprint-planning/SKILL.mdsrc/bmm-skills/plan/bmad-ux/SKILL.mdsrc/bmm-skills/ship/bmad-build/SKILL.mdsrc/bmm-skills/ship/bmad-checkpoint-preview/SKILL.mdsrc/bmm-skills/ship/bmad-code-review/SKILL.mdsrc/bmm-skills/ship/bmad-correct-course/SKILL.mdsrc/bmm-skills/ship/bmad-qa-generate-e2e-tests/SKILL.mdsrc/bmm-skills/ship/bmad-retrospective/SKILL.mdsrc/core-skills/bmad-deep-recon/SKILL.mdsrc/core-skills/bmad-forge-idea/SKILL.mdsrc/core-skills/bmad-review/SKILL.md
| --- | ||
| name: bmad-project-context | ||
| description: 'Set up or refresh agent instructions so AI agents work well in it. Use when the user says "project context", "set up AGENTS.md", "document this project", "refresh context", "audit context", wants to apply coding standards or governance to a repo, or wants to record a mistake agents keep making' | ||
| description: 'Set up or refresh a repository''s agent instructions — a small verified block in AGENTS.md — so AI agents work well in that repo. Use when the user says "project context", "set up AGENTS.md", "document this project", "refresh context", "audit context", wants to apply coding standards or governance to a repo, or wants to record a mistake agents keep making' |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Restore terminal punctuation in the three descriptions.
Append a period after the final activation phrase at each site.
src/bmm-skills/plan/bmad-project-context/SKILL.md#L3-L3: append.aftermaking.src/bmm-skills/plan/bmad-sprint-planning/SKILL.md#L3-L3: append.after"fix sprint status".src/bmm-skills/plan/bmad-ux/SKILL.md#L3-L3: append.after"help me plan the UX".
📍 Affects 3 files
src/bmm-skills/plan/bmad-project-context/SKILL.md#L3-L3(this comment)src/bmm-skills/plan/bmad-sprint-planning/SKILL.md#L3-L3src/bmm-skills/plan/bmad-ux/SKILL.md#L3-L3
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/bmm-skills/plan/bmad-project-context/SKILL.md` at line 3, Restore
terminal punctuation in the description at
src/bmm-skills/plan/bmad-project-context/SKILL.md:3-3 by appending a period
after “making”; apply the same punctuation-only update at
src/bmm-skills/plan/bmad-sprint-planning/SKILL.md:3-3 after “fix sprint status”
and at src/bmm-skills/plan/bmad-ux/SKILL.md:3-3 after “help me plan the UX”.
| --- | ||
| name: bmad-code-review | ||
| description: 'Adversarial code review using parallel review layers and structured triage. Use when the user says "run code review" or "review this code"' | ||
| description: 'Review code changes with several independent reviewers in parallel, then triage and present the findings. Use when the user says "run code review" or "review this code"' |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add terminal punctuation to both skill descriptions.
Both descriptions end without a final period. Add the period before the closing single quote in each file.
src/bmm-skills/ship/bmad-code-review/SKILL.md#L3-L3: add the final period.src/bmm-skills/ship/bmad-qa-generate-e2e-tests/SKILL.md#L3-L3: add the final period.
📍 Affects 2 files
src/bmm-skills/ship/bmad-code-review/SKILL.md#L3-L3(this comment)src/bmm-skills/ship/bmad-qa-generate-e2e-tests/SKILL.md#L3-L3
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/bmm-skills/ship/bmad-code-review/SKILL.md` at line 3, Add terminal
periods to the descriptions on line 3 of both
src/bmm-skills/ship/bmad-code-review/SKILL.md and
src/bmm-skills/ship/bmad-qa-generate-e2e-tests/SKILL.md, placing each period
before the closing single quote.
There was a problem hiding this comment.
Your trial has ended. Reactivate Greptile to resume code reviews.
Skill descriptions carried jargon and metaphor ("SPEC kernel",
"spine of invariants", "PRFAQ gauntlet", "dies cheaply") that bled
into interactive sessions, help output, and generated artifacts.
Rewrite the description layer in plain language, grounded in what
each skill's body actually does:
- SKILL.md frontmatter descriptions across bmm and core skills
- module-help.csv descriptions for bmm and core, restoring missing
punctuation, filling the empty create-epics-and-stories entry, and
spelling out CC/CR menu codes
- bmm module.yaml module description casing
- prfaq bmad-manifest.json capability description
"Use when the user says ..." trigger phrases are kept verbatim, and
agent persona descriptors in module.yaml are untouched.
Trailing periods on the description one-liners were inconsistent — most SKILL.md files had them, a handful did not. Review flagged the mismatch on the changed lines; resolve it the other way: no description ends with a period. Internal sentence punctuation is unchanged.
alexeyv
force-pushed
the
chore/plain-skill-descriptions
branch
from
August 10, 2026 10:36
ee6e89e to
7d2d60b
Compare
Greptile SummaryThe PR rewrites skill and catalog descriptions in clearer language without changing workflow behavior.
Confidence Score: 5/5The PR appears safe to merge because the metadata remains valid and the rewritten descriptions accurately reflect existing skill behavior. The changes are limited to user-facing descriptions, preserve parser-compatible formats and discovery triggers, and introduce no accepted functional or security failures.
|
| Filename | Overview |
|---|---|
| src/bmm-skills/module-help.csv | Rewrites BMad Method catalog descriptions, fills the epics-and-stories description, and preserves the valid 13-column CSV schema. |
| src/core-skills/module-help.csv | Rephrases Core catalog entries in plain language while preserving identifiers, routing fields, and CSV structure. |
| src/bmm-skills/plan/bmad-spec/SKILL.md | Replaces internal terminology with a plain-language description that remains consistent with the skill’s outputs and supported modes. |
| src/bmm-skills/plan/bmad-architecture/SKILL.md | Clarifies architecture creation, update, validation, and supported inputs without changing workflow instructions. |
| src/core-skills/bmad-deep-recon/SKILL.md | Describes the three supported research modes and built-in research types in more accessible language. |
| src/core-skills/bmad-review/SKILL.md | Rephrases multi-lens review behavior while retaining its supported inputs, lens selection, and discovery triggers. |
| src/bmm-skills/module.yaml | Corrects capitalization and hyphenation in the module’s user-facing description. |
| src/bmm-skills/plan/bmad-prfaq/bmad-manifest.json | Replaces metaphorical wording with an accurate description of the PRFAQ and optional condensed output. |
Reviews (1): Last reviewed commit: "style(skills): drop trailing periods fro..." | Re-trigger Greptile
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrites the skill description layer in plain language. Descriptions carried jargon and metaphor ("SPEC kernel + companions", "lean spine of invariants", "PRFAQ gauntlet", "hardens, proves out, or dies cheaply") that bled into interactive sessions, help output, and generated artifacts, and made the catalog hard to understand.
Changes
bmad-create-epics-and-storiesdescription, and spelled out the CC/CR menu-code references as Correct Course / Code Review.Deliberately unchanged
ARCHITECTURE-SPINE.md).module.yaml("Speaks like a treasure hunter…") — deliberate voice design, left for a separate decision.Validation
npm run validate:skills: 49 skills scanned, 0 findings.npm run qualitypasses.