Enhance CLI skills documentation for syntax verification #62
Conversation
…x against actual help output and clarify references for AI agents.
WalkthroughAdded mandatory CLI tool verification guidance to the writing skills guide: procedures to confirm tool existence, enumerate subcommands, verify syntax against actual Changes
Sequence Diagram(s)sequenceDiagram
participant Author as Author
participant Tool as CLI Tool
participant Docs as SKILL.md
rect rgb(230, 255, 230)
Note right of Author: Verification workflow (new)
end
Author->>Tool: run `tool --help` / check version
Tool-->>Author: help output, subcommands, flags, version
Author->>Docs: update CLI docs with exact flags & verified syntax
Docs-->>Author: annotated examples (GOOD/BETTER), CRITICAL notes, failure table
alt mismatch or missing
Author->>Tool: test subcommand syntax (runtime)
Tool-->>Author: success / error (adjust docs)
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 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: 0
🧹 Nitpick comments (1)
skills/writing-skills/SKILL.md (1)
339-345: Minor style issue: Reduce repeated "probably" phrasing in the table.The "Common CLI Documentation Failures" table repeats the word "probably" in two consecutive rows, which reduces stylistic variety and emphasis. Consider rewording one row to create clearer semantic distinction.
Current (lines 344–345):
- Row 3: "Flag names, structure vary between tools | Verify every example"
- Row 4: "Syntax is probably... | Probably wrong without verification | Test commands before documenting"
Suggested fix: Replace the second "Probably wrong" in Row 4 with a more direct statement like "Almost certainly wrong" or "Incorrect without verification."
| "Basic commands are obvious" | Flag names, structure vary between tools | Verify every example | - | "Syntax is probably..." | Probably wrong without verification | Test commands before documenting | + | "Syntax is probably..." | Almost certainly wrong without verification | Test commands before documenting |
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
skills/writing-skills/SKILL.md(7 hunks)
🧰 Additional context used
🪛 LanguageTool
skills/writing-skills/SKILL.md
[style] ~344-~344: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ific help | | "Syntax is probably..." | Probably wrong without verification | Test comma...
(REP_PROBABLY)
[style] ~362-~362: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...is tool works like..." - "The syntax is probably..." - "Most CLI tools use..." - "It sho...
(REP_PROBABLY)
🔇 Additional comments (3)
skills/writing-skills/SKILL.md (3)
323-366: Comprehensive CLI verification section is well-structured and actionable.The new "CLI Tool Verification (Critical)" section is effectively positioned and provides concrete, practical guidance. The five-step mandatory verification process is clear, the Common CLI Documentation Failures table concisely captures real pitfalls, and the verification examples with before/after patterns make the guidance immediately applicable. The red flags list helps writers self-detect when they're rationalizing, which aligns well with the document's theme of closing loopholes.
54-60: CLI verification requirements are consistently reinforced across the document.Verification is mentioned in "When to Create a Skill" (as a negative requirement), embedded in the checklist as a required item, referenced in code examples, and given a dedicated critical section. This multi-point reinforcement ensures the guidance is hard to miss and addresses the PR's motivation effectively. Well done.
Also applies to: 638-638
202-211: Token efficiency examples effectively demonstrate verification workflow.The progression from BAD (assumed) → GOOD (with --help reference) → BETTER (with verified example) is pedagogically sound and shows writers how to balance documentation brevity with the new verification requirement. This section integrates the new guidance without disrupting the existing CSO discussion.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
skills/writing-skills/SKILL.md (1)
349-366: Concrete examples and red flags work well; minor opportunity to vary phrasing for style.The BAD→GOOD→BETTER progression (lines 349–358) clearly demonstrates the verification workflow. Red flags section effectively lists rationalization patterns to catch. Consider varying phrasing in lines 361–364 to reduce repetition:
- "I assume this tool works like..." - "The syntax is probably..." - "Most CLI tools use..." - "It should be similar to..." + "I assume this tool works like..." + "Syntax is probably..." + "Most CLI tools must use..." + "It should be similar to..."Minor style improvement; no functional impact.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
skills/writing-skills/SKILL.md(7 hunks)
🧰 Additional context used
🪛 LanguageTool
skills/writing-skills/SKILL.md
[style] ~362-~362: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...is tool works like..." - "The syntax is probably..." - "Most CLI tools use..." - "It sho...
(REP_PROBABLY)
🔇 Additional comments (4)
skills/writing-skills/SKILL.md (4)
323-366: Well-structured mandatory CLI verification section with clear, actionable guidance.The new "CLI Tool Verification (Critical)" section is appropriately comprehensive—verification process, common failures table, concrete examples, and red flags work together effectively. Callouts throughout the document (lines 73, 466) properly reinforce criticality. Integration into the checklist (line 638) ensures compliance on every skill.
202-211: Token-efficiency section now properly models verification workflow.The updated examples (GOOD and BETTER) now emphasize
--helpverification and include verified-output annotations. Shift from "all flags in SKILL.md" to "reference --help for details" appropriately balances brevity with completeness.
54-60: Skill creation decision points now account for CLI verification requirements.Additions to "When to Create a Skill" (lines 54, 60) and "Skill Types" (line 73) properly gatekeep skills that rely on unverified CLI syntax. Placing CRITICAL guidance early signals priority without burying it.
Also applies to: 73-73
638-638: Checklist integration appropriately positions CLI verification in GREEN phase.Adding "Verify all CLI commands/syntax against actual
--helpoutput" as a discrete GREEN checklist item ensures verification happens before declaring the skill complete. Placement alongside other validation steps (code examples, agent compliance) maintains phase coherence.
|
Hi, Can you tell me a bit about what problem this is solving for you? The PR appears to have been written by an agent and doesn't talk about the real world problems you're fixing with it. |
2 participants
Enhanced the writing-skills documentation to emphasize critical verification of CLI command syntax against actual help output and clarify guidance for AI agents when documenting tool-based skills.
Motivation and Context
AI agents frequently make assumptions about CLI tool syntax without verification, leading to skills with incorrect command examples. This creates frustration when users follow documented commands that don't work. The writing-skills documentation needed stronger guidance on mandatory verification processes for any skill involving command-line tools or APIs.
This change addresses the pattern where skills document CLI syntax based on assumptions rather than verified help output, which undermines the reliability of the entire skills system.
How Has This Been Tested?
Breaking Changes
None. This is purely additive documentation that enhances existing guidelines without changing the fundamental skill creation process.
Types of changes
Checklist
Additional context
Key Enhancements Made:
--helpoutputImplementation Notes:
The changes ensure that future skills involving CLI tools will have accurate, verified syntax, improving the overall reliability and user experience of the skills system.
Summary by CodeRabbit