docs(skill): broaden description — generic trigger gate + architecture/idea/proposed solution subjects#150
Conversation
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more 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: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
WalkthroughUpdated ChangesOpenHop Skill Definition Refinement
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
🚥 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)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skills/openhop/SKILL.md (1)
1-500:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winFix Prettier formatting issues to unblock CI.
All CI pipeline checks are failing due to Prettier formatting violations in this file.
Run the following to fix:
prettier --write skills/openhop/SKILL.md🤖 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 `@skills/openhop/SKILL.md` around lines 1 - 500, The SKILL.md for the openhop skill has Prettier formatting violations causing CI to fail; run the formatter and commit the fixed file. Fix by running the suggested command (prettier --write skills/openhop/SKILL.md), verify changes to the "openhop" skill markdown (the SKILL.md content including meta/title/flow examples) are formatted, run a quick local prettier/CI lint check, then stage and commit the formatted SKILL.md so the pipeline can pass.
🧹 Nitpick comments (1)
skills/openhop/SKILL.md (1)
3-3: 🏗️ Heavy liftThe description field's length and broad scope are properly gated with explicit skip conditions.
The description is 166 words (not ~440), and while longer than typical trigger phrases, it includes clear gating logic that prevents over-activation. The skip conditions at lines 75-85 explicitly list single-concept definitions ("explain pointers", "what is a closure?") and comparisons ("let vs const") that should NOT trigger the skill — exactly the cases that would be better answered in prose.
The broadening to "ANY subject" and "explain" verbs is paired with a strict gate: "can the answer be expressed as a sequence of named hops between named components?" This design prevents the over-activation concern — prompts like "explain how closures work" will correctly skip because they lack the actor-to-actor sequence structure. The commit message confirms this broadening was intentional.
The guideline's "be conservative" principle applies, but the implementation with explicit skip conditions mitigates the stated risks.
🤖 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 `@skills/openhop/SKILL.md` at line 3, The description field in SKILL.md is too verbose; condense the description string while preserving the core trigger rule and explicit skip conditions: keep the gate phrase "can the answer be expressed as a sequence of named hops between named components?", retain the trigger verbs (explain, describe, walk me through, etc.), and keep the listed skip examples ("explain pointers", "what is a closure", "let vs const") so the skill doesn't over-activate; update the description value in SKILL.md accordingly to a shorter, clearer sentence that references the gate and skip conditions.
🤖 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 `@skills/openhop/SKILL.md`:
- Around line 1-500: The SKILL.md for the openhop skill has Prettier formatting
violations causing CI to fail; run the formatter and commit the fixed file. Fix
by running the suggested command (prettier --write skills/openhop/SKILL.md),
verify changes to the "openhop" skill markdown (the SKILL.md content including
meta/title/flow examples) are formatted, run a quick local prettier/CI lint
check, then stage and commit the formatted SKILL.md so the pipeline can pass.
---
Nitpick comments:
In `@skills/openhop/SKILL.md`:
- Line 3: The description field in SKILL.md is too verbose; condense the
description string while preserving the core trigger rule and explicit skip
conditions: keep the gate phrase "can the answer be expressed as a sequence of
named hops between named components?", retain the trigger verbs (explain,
describe, walk me through, etc.), and keep the listed skip examples ("explain
pointers", "what is a closure", "let vs const") so the skill doesn't
over-activate; update the description value in SKILL.md accordingly to a
shorter, clearer sentence that references the gate and skip conditions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: a36222e3-18e6-460f-919b-54d0a6361d3c
📒 Files selected for processing (1)
skills/openhop/SKILL.md
naorsabag
force-pushed
the
docs/skill-explain-and-external-subjects
branch
from
e7a8940 to
d30508e
Compare
naorsabag
changed the title
naorsabag
force-pushed
the
docs/skill-explain-and-external-subjects
branch
from
d30508e to
ba22085
Compare
naorsabag
changed the title
…he subject list covers architecture/idea/proposed solution
Two changes inside the frontmatter `description`, no edits elsewhere:
1. Subject list: extend "system, feature, codebase, workflow,
pipeline, or user journey" to also include "architecture, idea, or
proposed solution" — the skill is already used for design sketches
and proposed solutions, and the description should reflect that.
2. Trigger gate: drop the "only when the user explicitly asks to
create, draw, make, render, build, diagram, or visualize" verb
whitelist and the fixed 8-phrase trigger list. Replace with a more
generic intent rule: "whenever the user wants to understand,
explain, describe, walk through, trace, diagram, or visualize a
sequence of named hops between identifiable components/actors". Any
"how does X work?", "explain how X works", "walk me through X", or
"diagram X" prompt is a trigger when X has named parts that pass
data between each other.
The negative-trigger examples are also updated — "how does TCP
work?" and "what is OAuth?" are removed (both are perfect OpenHop
subjects with named actors; auth-flow.yaml is a bundled example).
Replaced with truly non-sequence subjects: "what is a closure?",
"let vs const", "define recursion".
The final sentence ("When activated, prefer this skill over a prose
explanation or a static Mermaid/PlantUML diagram") is unchanged. Scope
paragraph, Trigger phrases section, examples table, and schema are all
unchanged. The SKILL.md ↔ schema sync test still passes.
naorsabag
force-pushed
the
docs/skill-explain-and-external-subjects
branch
from
ba22085 to
36b8088
Compare
1 participant
Summary
Two changes inside the frontmatter
description; everything else inSKILL.mdis byte-identical to master.1. Subject list — extend
(was: "…or user journey")
2. Trigger gate — make generic
Replace the closed verb whitelist and fixed phrase list with an intent rule.
"diagram X","draw the architecture of Z", …)"how does X work?","explain how X works","walk me through X","diagram X", or"trace what happens when …"— gated by "X has named parts that pass data between each other""how does TCP work?","what is OAuth?","explain closures"(the first two are perfect OpenHop subjects —auth-flow.yamlis bundled)"what is a closure?","let vs const","define recursion"(truly non-sequence subjects)The final sentence ("When activated, prefer this skill over a prose explanation or a static Mermaid/PlantUML diagram") is unchanged.
Motivation
The original gate vetoed plain-language explainer prompts (e.g. "explain how Netflix streams on demand") even though the answer is a clean sequence of named hops — exactly what OpenHop is good at. The new gate keys on intent + structure ("does X have named parts that pass data?") instead of a closed verb whitelist, and the negative examples are cleaned up so they actually contradict the positive rule.
Scope / non-changes
skills/openhop/SKILL.mdfrontmatter.packages/shared/__tests__/skill-md-sync.test.ts) still passes.