Reduce the size and remove duplicate content on oversized SKILL.MD files#36
Conversation
|
Warning Rate limit exceeded
To continue reviewing without waiting, purchase usage credits in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughThis PR updates multiple workflow SKILL.md files to standardize Quick Start routing, add explicit failure-handling (stop, report, offer retry/escalation), remove extended phase-execution detail in several skills, and add concrete example-session sections to several guidelines.md files. ChangesWorkflow docs: quick-start, failure handling, examples
🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
triage/SKILL.md (1)
15-20:⚠️ Potential issue | 🔴 CriticalRouting bug confirmed: Line 18 routes directly to
skills/scan.mdeven when critical setup is skipped.Line 18 says: "If the user provided a Jira project key but no specific command, start with
skills/scan.md". However, this bypasses required setup:
skills/start.mdStep 4 creates.artifacts/triage/{PROJECT}/viamkdirskills/start.mdStep 3 validates Jira access before proceedingskills/scan.mdhas nomkdirpermission (allowed tools:jira_search+ write JSONs only)skills/scan.mdhas no Jira validation step (allowed tools: read-onlyjira_search)When a user provides only a project key, routing to
scan.mdskips artifact directory creation and access validation. The artifact writes will fail or write to the wrong location. Perguidelines.mdSafety: "Validate Jira access before scanning — fail fast if authentication is broken."Fix: Route to
skills/start.mdfirst even if the user provides a project key. Let Start validate and create the workspace, then recommend Scan.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@triage/SKILL.md` around lines 15 - 20, The routing currently sends a user-supplied Jira project key straight to skills/scan.md, which skips the setup steps in skills/start.md (the mkdir in Step 4 and Jira validation in Step 3); update the router so the branch that handles "project key provided but no specific command" invokes skills/start.md first (so Start performs the workspace mkdir and Jira access validation), and only after Start completes successfully proceed to or recommend executing skills/scan.md; ensure the routing change references the existing route condition that currently maps to skills/scan.md and call out skills/start.md Step 3 and Step 4 behavior so the setup/validation always runs before scanning.
🧹 Nitpick comments (4)
triage/guidelines.md (1)
69-83: ⚡ Quick winAdd a brief stop-on-failure note to the Example Session for consistency.
The “Example Session” (Line 69-83) demonstrates the happy path only. Since triage/SKILL and the PR objective standardize behavior (“stop and report; do not advance; offer retry/escalation”), adding a one-liner in the example will reduce the chance agents follow the example as an implicit control-flow contract.
🛠️ Suggested addition
/scan → fetches unresolved bugs + recently resolved bugs (90d window) → writes .artifacts/triage/EDM/issues.json and resolved.json /analyze → categorizes each bug; error signatures, duplicate confidence, regressionOf → reads resolved.json for regression hints; writes analyzed.json /report → generates interactive HTML dashboard → writes .artifacts/triage/EDM/report.html + +If any of the above steps fails or produces unexpected output: stop, report the error, and offer retry/escalation.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@triage/guidelines.md` around lines 69 - 83, The Example Session shows only the happy path and should include a one-line "stop-on-failure" note to enforce the triage SKILL control-flow; add a brief line after the session (near the block that lists /start, /scan, /analyze, /report, /assess) stating that on any failure the agent must "stop and report; do not advance; offer retry/escalation" (or equivalent), so readers of the Example Session and the listed commands (/start, /scan, /analyze, /report, /assess) see the required failure behavior inline with the happy path.cve-fix/guidelines.md (1)
93-103: ⚡ Quick winConsider adding one line on failure handling in the Example.
The example (Line 93-103) is a full walkthrough but doesn’t explicitly reflect the standardized stop/report/retry/escalation control flow when a phase step fails or produces unexpected output. Adding a short note makes the example less likely to be interpreted as a “continue anyway” flow.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cve-fix/guidelines.md` around lines 93 - 103, Add a single sentence to the Example after the numbered walkthrough that instructs what to do on failure: for any step (/start, /patch, /validate, /pr, /backport, /close) if a command fails or output is unexpected, stop the flow, write a failure report alongside the phase artifacts (e.g., context.md, patch-log.md, validation-results.md, pr-description.md, backport-log.md, close-report.md), attempt a defined retry where appropriate, and escalate to the maintainer/team if retries fail.skill-reviewer/SKILL.md (2)
16-19: ⚡ Quick winMake stop-on-failure behavior match PR-wide “retry/escalate” requirement.
Line [linenumber]16-17 correctly says to “stop and report,” but it doesn’t include the PR-wide policy stated in <pr_objectives>: “offer to retry or escalate” and “do not advance to the next phase.” Consider extending the failure-handling sentence(s) to include retry/escalation guidance (while keeping this SKILL.md concise, with details in
guidelines.md).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skill-reviewer/SKILL.md` around lines 16 - 19, Update the failure-handling sentence in SKILL.md (the paragraph that currently reads "If a step fails or produces unexpected output, stop and report the error to the user.") to also state that the agent must offer to retry the step or escalate per the PR-wide <pr_objectives> policy, and explicitly note that the agent must not advance to the next phase until retry/escalation is resolved; keep the wording concise and point readers to guidelines.md for full retry/escalation and escalation contact details.
13-15: ⚡ Quick winAlign Quick Start “missing target” behavior with
skills/review.md.Line [linenumber]14 says “the user must specify” the skill directory. But
skills/review.md(Process → Step 1) indicates that if the target dir is not specified, the workflow should ask. Consider rewording line [linenumber]14 to match that behavior (e.g., “If not specified, ask; otherwise readskills/review.md…”).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skill-reviewer/SKILL.md` around lines 13 - 15, Edit the Quick Start sentence in SKILL.md that currently states “the user must specify which skill directory to review” so it matches the behavior in skills/review.md Process → Step 1: change it to say that if the target skill directory is not specified the system should prompt/ask the user, and otherwise proceed to read skills/review.md to execute the review; ensure the new wording explicitly references prompting when missing and still points to commands/review.md for the /review flow.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@bugfix/guidelines.md`:
- Around line 67-81: Update the Example Session flow so the /test step follows
the global "stop and report; do not advance; offer retry or escalate" rule:
change the current line "if tests fail → return to /fix" under the /test step to
explicitly say something like "if tests fail → stop and report the error; do not
advance; offer retry of the failed step or escalate; if a retry is accepted
return to /fix". Ensure this wording appears in the Example Session sequence
(the block containing /assess, /reproduce, /diagnose, /fix, /test, /pr) so it
matches the global standardized behavior.
In `@bugfix/SKILL.md`:
- Around line 15-23: Update the SKILL.md description for the /unattended command
so it matches the actual workflow in skills/unattended.md: either append the
missing phases (/document and the session context manifest) to the listed chain
(diagnose → fix → test → review → document + session context) or replace the
specific chain with a generic phrase like “runs the unattended bugfix workflow
to completion”; edit the sentence mentioning /unattended (currently “runs
diagnose → fix → test → review to completion”) to reflect the chosen wording and
ensure it references /unattended and skills/unattended.md for consistency.
---
Outside diff comments:
In `@triage/SKILL.md`:
- Around line 15-20: The routing currently sends a user-supplied Jira project
key straight to skills/scan.md, which skips the setup steps in skills/start.md
(the mkdir in Step 4 and Jira validation in Step 3); update the router so the
branch that handles "project key provided but no specific command" invokes
skills/start.md first (so Start performs the workspace mkdir and Jira access
validation), and only after Start completes successfully proceed to or recommend
executing skills/scan.md; ensure the routing change references the existing
route condition that currently maps to skills/scan.md and call out
skills/start.md Step 3 and Step 4 behavior so the setup/validation always runs
before scanning.
---
Nitpick comments:
In `@cve-fix/guidelines.md`:
- Around line 93-103: Add a single sentence to the Example after the numbered
walkthrough that instructs what to do on failure: for any step (/start, /patch,
/validate, /pr, /backport, /close) if a command fails or output is unexpected,
stop the flow, write a failure report alongside the phase artifacts (e.g.,
context.md, patch-log.md, validation-results.md, pr-description.md,
backport-log.md, close-report.md), attempt a defined retry where appropriate,
and escalate to the maintainer/team if retries fail.
In `@skill-reviewer/SKILL.md`:
- Around line 16-19: Update the failure-handling sentence in SKILL.md (the
paragraph that currently reads "If a step fails or produces unexpected output,
stop and report the error to the user.") to also state that the agent must offer
to retry the step or escalate per the PR-wide <pr_objectives> policy, and
explicitly note that the agent must not advance to the next phase until
retry/escalation is resolved; keep the wording concise and point readers to
guidelines.md for full retry/escalation and escalation contact details.
- Around line 13-15: Edit the Quick Start sentence in SKILL.md that currently
states “the user must specify which skill directory to review” so it matches the
behavior in skills/review.md Process → Step 1: change it to say that if the
target skill directory is not specified the system should prompt/ask the user,
and otherwise proceed to read skills/review.md to execute the review; ensure the
new wording explicitly references prompting when missing and still points to
commands/review.md for the /review flow.
In `@triage/guidelines.md`:
- Around line 69-83: The Example Session shows only the happy path and should
include a one-line "stop-on-failure" note to enforce the triage SKILL
control-flow; add a brief line after the session (near the block that lists
/start, /scan, /analyze, /report, /assess) stating that on any failure the agent
must "stop and report; do not advance; offer retry/escalation" (or equivalent),
so readers of the Example Session and the listed commands (/start, /scan,
/analyze, /report, /assess) see the required failure behavior inline with the
happy path.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b64b3dd0-bac5-4801-9a98-2040c063168f
📒 Files selected for processing (9)
bugfix/SKILL.mdbugfix/guidelines.mdcve-fix/SKILL.mdcve-fix/guidelines.mddocs-writer/SKILL.mdkcs/SKILL.mdskill-reviewer/SKILL.mdtriage/SKILL.mdtriage/guidelines.md
adalton
left a comment
adalton
left a comment
There was a problem hiding this comment.
Four items — two bugs, one behavior change to confirm, one consistency question.
There was a problem hiding this comment.
🧹 Nitpick comments (1)
bugfix/SKILL.md (1)
15-16: 💤 Low valueConsider more explicit command enumeration for clarity.
Step 1 uses "a specific command (e.g.
/diagnose,/fix)" which relies on examples to exclude/unattended. For consistency with triage/SKILL.md line 17 (which explicitly enumerates: "(/start,/scan,/analyze,/report)"), consider either:
- Explicitly listing all phase commands in step 1, or
- Clarifying: "a specific phase command other than
/unattended"This would eliminate any ambiguity about which step matches
/unattended.♻️ Suggested wording options
Option 1: Enumerate commands explicitly
-1. If the user invoked a specific command (e.g. `/diagnose`, `/fix`), read `commands/{command}.md` and follow it. +1. If the user invoked a phase command (`/assess`, `/reproduce`, `/diagnose`, `/fix`, `/test`, `/review`, `/document`, `/pr`, `/feedback`), read `commands/{command}.md` and follow it.Option 2: Exclude /unattended explicitly
-1. If the user invoked a specific command (e.g. `/diagnose`, `/fix`), read `commands/{command}.md` and follow it. +1. If the user invoked a specific phase command other than `/unattended` (e.g. `/diagnose`, `/fix`), read `commands/{command}.md` and follow it.🤖 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 `@bugfix/SKILL.md` around lines 15 - 16, Clarify which commands map to the commands/{command}.md branch by either explicitly enumerating the phase commands (e.g., list `/diagnose`, `/fix`, etc.) or by rewording to "a specific phase command other than `/unattended`" so `/unattended` is not ambiguous with the commands/{command}.md path; update the line referencing commands/{command}.md and the skills/unattended.md distinction to use one of these two phrasings for consistency with the triage/SKILL.md enumeration.
🤖 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.
Nitpick comments:
In `@bugfix/SKILL.md`:
- Around line 15-16: Clarify which commands map to the commands/{command}.md
branch by either explicitly enumerating the phase commands (e.g., list
`/diagnose`, `/fix`, etc.) or by rewording to "a specific phase command other
than `/unattended`" so `/unattended` is not ambiguous with the
commands/{command}.md path; update the line referencing commands/{command}.md
and the skills/unattended.md distinction to use one of these two phrasings for
consistency with the triage/SKILL.md enumeration.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a3b7e594-8271-440d-a82a-16e6c23f02b3
📒 Files selected for processing (4)
bugfix/SKILL.mdbugfix/guidelines.mdskill-reviewer/SKILL.mdtriage/SKILL.md
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skill-reviewer/SKILL.md (1)
16-75:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winResolve merge-conflict markers and drop the duplicated long block.
<<<<<<< / ======= / >>>>>>>left in the file is blocking (lint/parsing) and it also bloatsSKILL.mdbeyond the concise orchestrator format.Suggested fix
-<<<<<<< skill-updates If a step fails or produces unexpected output, stop and report the error to the user. Do not advance to the next phase. Offer to retry the failed step or escalate. For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`. -======= -1. Read every file in the target skill directory: `SKILL.md`, `skills/*.md`, `commands/*.md`, `guidelines.md`, `README.md`. If the directory doesn't exist or has no skill files, report the error and stop. Note any missing files — gaps are themselves a finding. -2. Run automated pre-review checks: `python3 {skill-reviewer-dir}/scripts/pre-review-checks.py {target-dir}` — captures structural, frontmatter, reference, and sequencing issues deterministically. Treat `FAIL` results as pre-validated findings; apply judgment to `WARN` results. If the script is not present, skip and check manually. -3. Evaluate against 8 dimensions (use automated check results as pre-validated evidence where available): - - **Orchestration & Routing** — correct routing, no orphaned/dangling references, executable Quick Start - - **Step Sequencing** — sequential numbering, correct cross-references, logical order - - **Schema Consistency** — matching field names/types across files, schema visible before first use - - **Cognitive Load** — flag skills with >10 steps, synthesis after heavy processing, missing batching - - **Instruction Clarity** — unambiguous, first-try-correct, clear when-to-use vs when-to-skip - - **Documentation & Project Alignment** — README matches implementation, consistent with sibling skills and project conventions - - **Command Naming** — consistent pattern (verbs vs nouns), self-explanatory - - **Error Handling** — failure modes documented, escalation paths clear -4. Classify each finding by severity — **CRITICAL** / **HIGH** (blockers) or **MEDIUM** / **LOW** (suggestions). -5. Validate findings: verify each finding cites a specific file, includes a concrete suggestion, and that blocker/suggestion counts are accurate. Drop any finding you cannot substantiate from the files you read. -6. Produce a structured report and write it to `.artifacts/skill-reviewer/{skill-name}/review.md`: - -``` -## Skill Review: {skill-name} - -[2-3 sentence overall assessment] - -### Strengths -- [What's well-done] - -### Findings - -| # | Severity | File | Finding | Suggestion | -|---|----------|------|---------|------------| -| 1 | HIGH | skills/scan.md | ... | ... | - -### Summary - -- **Blockers**: {count} -- **Suggestions**: {count} -- **Verdict**: [one-line summary] -``` - -## File Layout - -```text -skill-reviewer/ - SKILL.md # This file — workflow overview and routing - guidelines.md # Principles, hard limits, safety, quality standards - README.md # User-facing documentation - commands/ - review.md # /review command — loads guidelines + skill - prompts/ - analyze-skill.md # Prompt template for Explore sub-agent (large skill reading) - skills/ - review.md # The review skill (detailed steps and output format) - scripts/ - pre-review-checks.py # Automated structural/reference/sequencing checks -``` ->>>>>>> mainAs per coding guidelines: “Keep SKILL.md under 30 lines using progressive disclosure — place detailed behavioral rules, phase details, and implementation specifics in guidelines.md and skills/ files instead”.
🤖 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 `@skill-reviewer/SKILL.md` around lines 16 - 75, File SKILL.md contains unresolved git merge conflict markers (<<<<<<<, =======, >>>>>>>) and a duplicated long block; remove the entire conflict region and keep only the concise orchestrator content. Specifically, delete everything from the `<<<<<<< skill-updates` marker through the `>>>>>>> main` marker, leaving a single short SKILL.md that references `guidelines.md`/`skills/*` for details; ensure no leftover markers remain and that long behavioral/detail content is moved into guidelines.md or the appropriate files (e.g., `skills/review.md`, `guidelines.md`) per the orchestrator format.
🤖 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.
Outside diff comments:
In `@skill-reviewer/SKILL.md`:
- Around line 16-75: File SKILL.md contains unresolved git merge conflict
markers (<<<<<<<, =======, >>>>>>>) and a duplicated long block; remove the
entire conflict region and keep only the concise orchestrator content.
Specifically, delete everything from the `<<<<<<< skill-updates` marker through
the `>>>>>>> main` marker, leaving a single short SKILL.md that references
`guidelines.md`/`skills/*` for details; ensure no leftover markers remain and
that long behavioral/detail content is moved into guidelines.md or the
appropriate files (e.g., `skills/review.md`, `guidelines.md`) per the
orchestrator format.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 83a2a42c-8de0-466d-8a09-9bad2b25df80
📒 Files selected for processing (2)
bugfix/SKILL.mdskill-reviewer/SKILL.md
2 participants
Redundant or overly detailed step-by-step examples have been removed from the main
SKILL.mdfiles, with a focus on concise, actionable instructions.Standardized error handling and phase transitions:
SKILL.mdfiles (bugfix,cve-fix,docs-writer,kcs,triage, andskill-reviewer) now include the rule: if a step fails or produces unexpected output, stop and report the error to the user; do not advance to the next phase, and offer to retry or escalate. This ensures safer and more predictable workflow execution.Documentation and example improvements:
SKILL.mdfiles, making the documentation more concise and focused on high-level workflow orchestration.guidelines.mdfiles forbugfixandcve-fix, providing clear, concrete examples of end-to-end workflow execution.These changes improve consistency, safety, and clarity across all skill workflows.
Summary by CodeRabbit