chore(skills): rewrite skill descriptions in plain language - #2701
Merged
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.
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 help-catalog descriptions in plainer language without changing executable workflows.
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| src/bmm-skills/module-help.csv | Rewrites user-facing catalog descriptions while preserving the valid 13-column CSV structure. |
| src/core-skills/module-help.csv | Simplifies descriptions for Review, Forge Idea, and Deep Recon without changing catalog fields. |
| src/bmm-skills/plan/bmad-ux/SKILL.md | Clarifies that DESIGN.md and EXPERIENCE.md are the skill’s two primary UX documents. |
| src/bmm-skills/plan/bmad-prfaq/SKILL.md | Replaces abstract PRFAQ language with a concrete explanation of the Working Backwards workflow. |
| src/core-skills/bmad-deep-recon/SKILL.md | Restates the skill’s research modes and supported research types in plain language. |
| src/bmm-skills/module.yaml | Corrects capitalization and hyphenation in the module description. |
Reviews (2): Last reviewed commit: "style(skills): drop trailing periods fro..." | Re-trigger Greptile
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 11, 2026 19:19
7d2d60b to
d10b99b
Compare
This was referenced Aug 12, 2026
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.