Extract writing-skills appendices to separate reference doc #365
Conversation
Reduce SKILL.md from 656 to 232 lines by extracting detailed reference material to SKILL_AUTHORING_DETAILS.md: - CSO advanced techniques (keyword coverage, token efficiency) - Flowchart usage guidelines - Code examples guidelines - File organization examples - Testing different skill types - Common rationalizations table - Bulletproofing against rationalization - Anti-patterns Core workflow remains in SKILL.md with links to detailed reference.
📝 WalkthroughWalkthroughThis PR streamlines skill authoring docs by slimming Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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
🤖 Fix all issues with AI agents
In `@skills/writing-skills/SKILL_AUTHORING_DETAILS.md`:
- Line 126: Replace the force-loading `@graphviz-conventions.dot` reference with
a plain mention to avoid the `@` link; specifically change the string
`@graphviz-conventions.dot` to `graphviz-conventions.dot` (or "See
graphviz-conventions.dot for graphviz style rules") in
SKILL_AUTHORING_DETAILS.md so it no longer uses the `@` prefix that triggers a
force-load.
In `@skills/writing-skills/SKILL.md`:
- Line 168: Replace the force-load @ link in the "Testing methodology:" line by
removing the leading @ so it reads a plain reference; specifically change the
string "@testing-skills-with-subagents.md" to "testing-skills-with-subagents.md"
(or similar plain-text reference) in SKILL.md so the line becomes "See
testing-skills-with-subagents.md for pressure scenarios, pressure types, and
meta-testing techniques." This avoids preloading context while preserving the
pointer to the testing document.
🧹 Nitpick comments (3)
skills/writing-skills/SKILL_AUTHORING_DETAILS.md (2)
138-138: Use a real heading instead of bold text. This avoids MD036 and improves scan-ability.🧹 Proposed fix
-**One excellent example beats many mediocre ones** +### One excellent example beats many mediocre ones
164-185: Specify languages for fenced code blocks. markdownlint (MD040) flags these;textis sufficient for directory trees and examples.🧹 Proposed fix
-``` +```text defense-in-depth/ SKILL.md # Everything inline -``` +``` -``` +```text condition-based-waiting/ SKILL.md # Overview + patterns example.ts # Working helpers to adapt -``` +``` -``` +```text pptx/ SKILL.md # Overview + workflows pptxgenjs.md # 600 lines API reference ooxml.md # 500 lines XML structure scripts/ # Executable tools -``` +``` -```markdown +```markdown Write code before test? Delete it. Start over. **No exceptions:** - Don't keep it as "reference" - Don't "adapt" it while writing tests - Don't look at it - Delete means delete -``` +```Also applies to: 283-283
skills/writing-skills/SKILL.md (1)
111-115: Prefer a heading over bold emphasis here. Aligns with MD036 and makes the section easier to scan.🧹 Proposed fix
-**CRITICAL: Description = When to Use, NOT What the Skill Does** +### CRITICAL: Description = When to Use, NOT What the Skill Does
Addresses CodeRabbit review feedback - @ syntax preloads context unnecessarily, contradicting our own CSO guidance.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@skills/writing-skills/SKILL_AUTHORING_DETAILS.md`:
- Around line 164-184: Add the language identifier "text" to each fenced code
block that lists directory layouts or plain snippets (the blocks beginning with
"defense-in-depth/", "condition-based-waiting/", "pptx/" and the standalone
"Write code before test? Delete it. Start over.") so markdownlint MD040 is
satisfied; update each opening fence from ``` to ```text while leaving the block
contents unchanged and keep the closing ``` as-is.
- Line 138: Convert the bold-only line "**One excellent example beats many
mediocre ones**" into a proper Markdown heading to satisfy MD036; replace the
emphasis with an appropriate heading level (e.g., "## One excellent example
beats many mediocre ones" or another level that fits the surrounding sections)
so the line becomes a real heading instead of bold text.
In `@skills/writing-skills/SKILL.md`:
- Around line 109-115: Replace the bold emphasis line under the "Description
Field" section with a proper Markdown heading to satisfy MD036: find the bold
text "CRITICAL: Description = When to Use, NOT What the Skill Does" and change
it to a heading (e.g., "### CRITICAL: Description = When to Use, NOT What the
Skill Does") so it is a semantic heading rather than emphasized text; ensure
spacing and heading level match surrounding "Description Field" content.
|
|
||
| ## Code Examples Guidelines | ||
|
|
||
| **One excellent example beats many mediocre ones** |
There was a problem hiding this comment.
Use a heading instead of bold-only line (MD036).
Markdownlint flags emphasis-as-heading here; consider promoting it to a heading to avoid lint failures.
💡 Proposed fix
-**One excellent example beats many mediocre ones**
+### One excellent example beats many mediocre ones📝 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.
| **One excellent example beats many mediocre ones** | |
| ### One excellent example beats many mediocre ones |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
138-138: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In `@skills/writing-skills/SKILL_AUTHORING_DETAILS.md` at line 138, Convert the
bold-only line "**One excellent example beats many mediocre ones**" into a
proper Markdown heading to satisfy MD036; replace the emphasis with an
appropriate heading level (e.g., "## One excellent example beats many mediocre
ones" or another level that fits the surrounding sections) so the line becomes a
real heading instead of bold text.
| ``` | ||
| defense-in-depth/ | ||
| SKILL.md # Everything inline | ||
| ``` | ||
| When: All content fits, no heavy reference needed | ||
|
|
||
| ### Skill with Reusable Tool | ||
| ``` | ||
| condition-based-waiting/ | ||
| SKILL.md # Overview + patterns | ||
| example.ts # Working helpers to adapt | ||
| ``` | ||
| When: Tool is reusable code, not just narrative | ||
|
|
||
| ### Skill with Heavy Reference | ||
| ``` | ||
| pptx/ | ||
| SKILL.md # Overview + workflows | ||
| pptxgenjs.md # 600 lines API reference | ||
| ooxml.md # 500 lines XML structure | ||
| scripts/ # Executable tools |
There was a problem hiding this comment.
Add language identifiers to fenced blocks (MD040).
The fenced blocks without a language will trigger markdownlint. Use text (or plaintext) since these are directory layouts/snippets.
💡 Proposed fix
-```
+```text
defense-in-depth/
SKILL.md # Everything inline@@
- +text
condition-based-waiting/
SKILL.md # Overview + patterns
example.ts # Working helpers to adapt
@@
-```
+```text
pptx/
SKILL.md # Overview + workflows
pptxgenjs.md # 600 lines API reference
ooxml.md # 500 lines XML structure
scripts/ # Executable tools
@@
- +text
Write code before test? Delete it. Start over.
@@
- +
</details>
Also applies to: 283-283
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>
164-164: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
---
171-171: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
---
179-179: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @skills/writing-skills/SKILL_AUTHORING_DETAILS.md around lines 164 - 184, Add
the language identifier "text" to each fenced code block that lists directory
layouts or plain snippets (the blocks beginning with "defense-in-depth/",
"condition-based-waiting/", "pptx/" and the standalone "Write code before test?
Delete it. Start over.") so markdownlint MD040 is satisfied; update each opening
fence from totext while leaving the block contents unchanged and keep
the closing ``` as-is.
</details>
<!-- fingerprinting:phantom:triton:eagle -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ### Description Field | ||
|
|
||
| **CRITICAL: Description = When to Use, NOT What the Skill Does** | ||
|
|
||
| The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description. | ||
|
|
||
| **Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality). | ||
| The description should ONLY describe triggering conditions. Do NOT summarize the skill's workflow. | ||
|
|
||
| When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process. | ||
|
|
||
| **The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips. | ||
| **Why:** Testing revealed that when descriptions summarize workflow, Claude follows the description instead of reading the full skill content. |
There was a problem hiding this comment.
Convert bold “CRITICAL” line to a heading (MD036).
Markdownlint flags emphasis-as-heading; promoting to a heading avoids lint failures.
💡 Proposed fix
-**CRITICAL: Description = When to Use, NOT What the Skill Does**
+#### CRITICAL: Description = When to Use, NOT What the Skill Does📝 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.
| ### Description Field | |
| **CRITICAL: Description = When to Use, NOT What the Skill Does** | |
| The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description. | |
| **Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality). | |
| The description should ONLY describe triggering conditions. Do NOT summarize the skill's workflow. | |
| When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process. | |
| **The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips. | |
| **Why:** Testing revealed that when descriptions summarize workflow, Claude follows the description instead of reading the full skill content. | |
| ### Description Field | |
| #### CRITICAL: Description = When to Use, NOT What the Skill Does | |
| The description should ONLY describe triggering conditions. Do NOT summarize the skill's workflow. | |
| **Why:** Testing revealed that when descriptions summarize workflow, Claude follows the description instead of reading the full skill content. |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
111-111: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In `@skills/writing-skills/SKILL.md` around lines 109 - 115, Replace the bold
emphasis line under the "Description Field" section with a proper Markdown
heading to satisfy MD036: find the bold text "CRITICAL: Description = When to
Use, NOT What the Skill Does" and change it to a heading (e.g., "### CRITICAL:
Description = When to Use, NOT What the Skill Does") so it is a semantic heading
rather than emphasized text; ensure spacing and heading level match surrounding
"Description Field" content.
2 participants
Summary
writing-skills/SKILL.mdfrom 656 to 232 lines (65% reduction)SKILL_AUTHORING_DETAILS.mdWhat was extracted
Why
Skills that are loaded frequently benefit from being concise. The detailed reference material is valuable but doesn't need to be in the main workflow - it can be referenced when needed.
Testing
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.