Merge branch 'main' into fix/issue-75-docs-inconsistency-conflicting-skill-des

Resolves conflict in AGENTS.md introduced by #170 (empty scripts/
directory cleanup). Combines #170's '## Usage (Optional)' + scripts/
explanation with this PR's equivalent-headings note.

AGENTS.md

@@ -119,7 +119,9 @@ description: {One sentence describing what the skill does, followed by one or mo
 
 Equivalent headings like `Workflow`, `Core Process`, or `When to Use` are fine when they communicate the same structure clearly.
 
-## Usage
+## Usage (Optional)
+
+Include this section only if the skill ships runnable helpers under `scripts/`. Markdown-only skills can omit both the section and the directory entirely.
 
 ```bash
 bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]

CONTRIBUTING.md

@@ -41,6 +41,7 @@ The frontmatter fields above are required. The section anatomy is a recommended
 - Don't duplicate content between skills — reference other skills instead
 - Don't add skills that are vague advice instead of actionable processes
 - Don't create supporting files unless content exceeds 100 lines
+- Don't create an empty `scripts/` directory just to match another skill — add `scripts/` only when the skill includes runnable helpers
 - Don't put reference material inside skill directories — use `references/` instead
 
 ## Modifying Existing Skills

docs/skill-anatomy.md

@@ -10,9 +10,12 @@ Every skill lives in its own directory under `skills/`:
 skills/
   skill-name/
     SKILL.md           # Required: The skill definition
+    scripts/           # Optional: Runnable helpers used by the skill workflow
     supporting-file.md # Optional: Reference material loaded on demand
 ```
 
+`SKILL.md` is the only required file. Add `scripts/` only when the skill actually ships runnable helpers, and omit the directory entirely for markdown-only skills.
+
 ## SKILL.md Format
 
 ### Frontmatter (Required)
@@ -102,6 +105,8 @@ Create supporting files only when:
 
 Keep patterns and principles inline when under 50 lines.
 
+If a skill does not need runnable helpers, do not create an empty `scripts/` directory just to mirror other skills. Empty directories add noise without changing how the skill works.
+
 ## Writing Principles
 
 1. **Process over knowledge.** Skills are workflows, not reference docs. Steps, not facts.

skills/browser-testing-with-devtools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browser-testing-with-devtools
-description: Tests in real browsers. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data via Chrome DevTools MCP.
+description: Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured.
 ---
 
 # Browser Testing with DevTools

skills/idea-refine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: idea-refine
-description: Refines ideas iteratively. Refine ideas through structured divergent and convergent thinking. Use "idea-refine" or "ideate" to trigger.
+description: Refines raw ideas into sharp, actionable concepts through structured divergent and convergent thinking. Use when an idea is still vague, when you need to stress-test assumptions before committing to a plan, or when you want to expand options before converging on one. Triggers on "ideate", "refine this idea", or "stress-test my plan".
 ---
 
 # Idea Refine

skills/spec-driven-development/SKILL.md

@@ -160,7 +160,7 @@ Break the plan into discrete, implementable tasks:
 
 ### Phase 4: Implement
 
-Execute tasks one at a time following `incremental-implementation` and `test-driven-development` skills. Use `context-engineering` to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.
+Execute tasks one at a time following `skills/incremental-implementation/SKILL.md` (`incremental-implementation`) and `skills/test-driven-development/SKILL.md` (`test-driven-development`). Use `skills/context-engineering/SKILL.md` (`context-engineering`) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.
 
 ## Keeping the Spec Alive