fix(skill): improve bmad-help description for accurate trigger matching#2012
Merged
fix(skill): improve bmad-help description for accurate trigger matching#2012
Conversation
🤖 Augment PR SummarySummary: Refines the 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
src/core/skills/bmad-help/SKILL.md
Outdated
| --- | ||
| name: bmad-help | ||
| description: 'Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now' | ||
| description: 'Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, asks a question about BMad, or invokes /bmad-help' |
There was a problem hiding this comment.
The description mentions invoking /bmad-help but not the canonical bmad-help form (docs indicate plain bmad-help should work everywhere, with /... being platform-dependent). Consider referencing bmad-help (optionally alongside /bmad-help) to avoid confusing users/platforms.
Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
Refined through adversarial review to accurately reflect the skills state-analysis, question-answering, and workflow-recommendation capabilities with precise trigger phrases that avoid false positives. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
📝 WalkthroughWalkthroughUpdated the front matter description in the bmad-help skill to expand its scope from narrowly advising on next steps to broadly addressing BMad questions and recommending workflows or agents, including the /bmad-help trigger phrase. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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: 1
🧹 Nitpick comments (6)
src/core/skills/bmad-help/SKILL.md (6)
3-3: No explicit BMAD namespace tokens beyond “BMad” increases ambiguity.Line 3 would be safer if it keyed to concrete BMAD entities (workflow, agent, phase, quick-flow, PRD, etc.) instead of a single brand token.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/skills/bmad-help/SKILL.md` at line 3, The description field in SKILL.md is too vague by using only the brand token "BMad"; update the description to explicitly mention BMAD domain entities so intent is unambiguous — modify the description value in SKILL.md (the description key) to list concrete tokens such as workflow, agent, phase, quick-flow, PRD, and the /bmad-help trigger (e.g., "Analyzes current state and user query to answer BMad questions or recommend next workflow, agent, phase, quick-flow, PRD actions; use when user asks 'what should I do next', 'what do I do now', or invokes /bmad-help"). Ensure all mentioned BMAD entity names match canonical project terms.
3-3: Trigger phrase matching is too literal and brittle.Line 3 encodes exact phrasings (“what should I do next”, “what do I do now”) but omits normalized intent language, so semantically equivalent prompts may miss the trigger.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/skills/bmad-help/SKILL.md` at line 3, The skill's description field in SKILL.md uses literal trigger phrases which are brittle; update the description to reference normalized intents and broader trigger patterns instead of exact strings (e.g., mention "asks what to do next / what now" as an intent or reference regex/intent matching like “next-step” or “next-action” triggers), and add examples or synonyms (e.g., "what should I do next", "what do I do now", "what's my next step", "how do I proceed", "/bmad-help") so the trigger logic (description) covers semantically equivalent prompts—edit the description line in SKILL.md to use intent-based wording and include representative synonyms rather than only the exact phrases.
3-3: No explicit exclusion for support/setup intents can misroute install questions.Line 3 should exclude installation/platform-enablement support if those are handled by dedicated skills; otherwise bmad-help becomes an accidental catch-all.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/skills/bmad-help/SKILL.md` at line 3, The SKILL.md description for the bmad-help skill is currently too broad and may capture installation/platform-enablement support; update the skill metadata (the description field in SKILL.md and/or add an explicit exclusion list) to explicitly exclude install/setup/platform-enablement/support intents (e.g., "not for installation, setup, or platform-enablement/support requests") so those queries route to their dedicated skills; reference the bmad-help description and the /bmad-help invocation when making the change.
3-3: No tie-break rule between “answer question” vs “recommend next workflow/agent.”Line 3 defines two behaviors but no precedence. Without a tie-breaker, similar prompts can produce different outcomes across runs.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/skills/bmad-help/SKILL.md` at line 3, The SKILL.md description currently lists two behaviors ("answer BMad questions" and "recommend next workflow/agent") with no precedence; update the description to add a explicit tie-break rule so outputs are deterministic—for example: prefer "answer question" when the user input contains an explicit question or question mark, otherwise default to "recommend next workflow/agent" for procedural/next-step prompts; reference the SKILL.md description and the trigger "/bmad-help" so the rule is applied to both natural-language invokes and the command.
3-3: Description still encodes behavioral policy that should be testable but isn’t machine-structured.Line 3 is free-form prose; this makes reliable trigger validation harder. Consider representing trigger intents as discrete bullets or structured keys in frontmatter to support stable tests.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/skills/bmad-help/SKILL.md` at line 3, The free-form "description" in SKILL.md encodes trigger behavior; change it to a machine-structured frontmatter field (e.g., add a "triggers" or "trigger_intents" array) so tests can assert specific intents; update SKILL.md by replacing or augmenting the description key with discrete items like "triggers:" or "trigger_intents:" containing explicit strings such as "ask_next_step", "ask_now", "ask_bmad_question", and "/bmad-help" to represent each activation phrase, and ensure any code reading SKILL.md (e.g., skill loader that inspects description) is updated to prefer the new key name when validating triggers.
3-3: Invocation and semantic triggers are mixed into one long clause.Line 3 combines
/bmad-helpcommand invocation with natural-language triggers in the same sentence; separating these improves deterministic matching and future maintenance.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/skills/bmad-help/SKILL.md` at line 3, Split the combined invocation and semantic triggers in the description field so they are distinct: keep a concise functional description for the skill in the existing description (what it does — e.g., "Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent") and move the invocation details into a separate sentence or a new "invocation" stanza that specifies the deterministic trigger "/bmad-help" and a separate "triggers" sentence listing natural-language cues ("what should I do next", "what do I do now", questions about BMad). Update the SKILL.md description line accordingly and ensure the exact token "/bmad-help" and the natural-language trigger examples are present in their own place for clarity and maintainability.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/core/skills/bmad-help/SKILL.md`:
- Line 3: Update the SKILL.md description for the BMad-help skill to include an
explicit negative scope that prevents triggering on generic help queries; edit
the description string (the line containing description: 'Analyzes current
state...') to append a clear "Do not trigger when..." clause (e.g., "Do not
trigger for generic 'help me' or unrelated support requests without any
BMAD-specific context or mention of BMad, BMAD workflow, agent, or relevant task
identifiers") so the skill only activates when BMAD context or explicit user
intent for BMad is present.
---
Nitpick comments:
In `@src/core/skills/bmad-help/SKILL.md`:
- Line 3: The description field in SKILL.md is too vague by using only the brand
token "BMad"; update the description to explicitly mention BMAD domain entities
so intent is unambiguous — modify the description value in SKILL.md (the
description key) to list concrete tokens such as workflow, agent, phase,
quick-flow, PRD, and the /bmad-help trigger (e.g., "Analyzes current state and
user query to answer BMad questions or recommend next workflow, agent, phase,
quick-flow, PRD actions; use when user asks 'what should I do next', 'what do I
do now', or invokes /bmad-help"). Ensure all mentioned BMAD entity names match
canonical project terms.
- Line 3: The skill's description field in SKILL.md uses literal trigger phrases
which are brittle; update the description to reference normalized intents and
broader trigger patterns instead of exact strings (e.g., mention "asks what to
do next / what now" as an intent or reference regex/intent matching like
“next-step” or “next-action” triggers), and add examples or synonyms (e.g.,
"what should I do next", "what do I do now", "what's my next step", "how do I
proceed", "/bmad-help") so the trigger logic (description) covers semantically
equivalent prompts—edit the description line in SKILL.md to use intent-based
wording and include representative synonyms rather than only the exact phrases.
- Line 3: The SKILL.md description for the bmad-help skill is currently too
broad and may capture installation/platform-enablement support; update the skill
metadata (the description field in SKILL.md and/or add an explicit exclusion
list) to explicitly exclude install/setup/platform-enablement/support intents
(e.g., "not for installation, setup, or platform-enablement/support requests")
so those queries route to their dedicated skills; reference the bmad-help
description and the /bmad-help invocation when making the change.
- Line 3: The SKILL.md description currently lists two behaviors ("answer BMad
questions" and "recommend next workflow/agent") with no precedence; update the
description to add a explicit tie-break rule so outputs are deterministic—for
example: prefer "answer question" when the user input contains an explicit
question or question mark, otherwise default to "recommend next workflow/agent"
for procedural/next-step prompts; reference the SKILL.md description and the
trigger "/bmad-help" so the rule is applied to both natural-language invokes and
the command.
- Line 3: The free-form "description" in SKILL.md encodes trigger behavior;
change it to a machine-structured frontmatter field (e.g., add a "triggers" or
"trigger_intents" array) so tests can assert specific intents; update SKILL.md
by replacing or augmenting the description key with discrete items like
"triggers:" or "trigger_intents:" containing explicit strings such as
"ask_next_step", "ask_now", "ask_bmad_question", and "/bmad-help" to represent
each activation phrase, and ensure any code reading SKILL.md (e.g., skill loader
that inspects description) is updated to prefer the new key name when validating
triggers.
- Line 3: Split the combined invocation and semantic triggers in the description
field so they are distinct: keep a concise functional description for the skill
in the existing description (what it does — e.g., "Analyzes current state and
user query to answer BMad questions or recommend the next workflow or agent")
and move the invocation details into a separate sentence or a new "invocation"
stanza that specifies the deterministic trigger "/bmad-help" and a separate
"triggers" sentence listing natural-language cues ("what should I do next",
"what do I do now", questions about BMad). Update the SKILL.md description line
accordingly and ensure the exact token "/bmad-help" and the natural-language
trigger examples are present in their own place for clarity and maintainability.
🪄 Autofix (Beta)
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
Run ID: 4a31af79-3386-494e-bb82-9f70b296fbfd
📒 Files selected for processing (1)
src/core/skills/bmad-help/SKILL.md
src/core/skills/bmad-help/SKILL.md
Outdated
| --- | ||
| name: bmad-help | ||
| description: 'Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now' | ||
| description: 'Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, asks a question about BMad, or invokes /bmad-help' |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add an explicit negative scope to reduce false positives.
Line 3 still doesn’t state when not to trigger (e.g., generic “help me” without BMAD context), which directly risks the false-positive case in your own test plan.
Proposed change
-description: 'Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, asks a question about BMad, or invokes /bmad-help'
+description: 'Analyzes BMAD project state and user query to answer BMAD-specific questions or recommend the next workflow/agent. Use when user asks BMAD next-step questions, explicitly asks about BMAD methods/workflows/agents, or invokes /bmad-help. Do not trigger for generic non-BMAD help requests.'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| description: 'Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, asks a question about BMad, or invokes /bmad-help' | |
| description: 'Analyzes BMAD project state and user query to answer BMAD-specific questions or recommend the next workflow/agent. Use when user asks BMAD next-step questions, explicitly asks about BMAD methods/workflows/agents, or invokes /bmad-help. Do not trigger for generic non-BMAD help requests.' |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/core/skills/bmad-help/SKILL.md` at line 3, Update the SKILL.md
description for the BMad-help skill to include an explicit negative scope that
prevents triggering on generic help queries; edit the description string (the
line containing description: 'Analyzes current state...') to append a clear "Do
not trigger when..." clause (e.g., "Do not trigger for generic 'help me' or
unrelated support requests without any BMAD-specific context or mention of BMad,
BMAD workflow, agent, or relevant task identifiers") so the skill only activates
when BMAD context or explicit user intent for BMad is present.
alexeyv
force-pushed
the
fix-bmad-help-description
branch
from
59aaa48 to
baa27fc
Compare
bmadcode
approved these changes
Mar 15, 2026
3 tasks
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
2 participants
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.
Summary
Test plan
Generated with Claude Code