From 0e497aa1f1cca86d139727f14bfc77cb6b0f10e0 Mon Sep 17 00:00:00 2001 From: TianTian Date: Tue, 12 May 2026 09:12:13 +0800 Subject: [PATCH 1/4] fix codex cross-skill references --- skills/spec-driven-development/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/spec-driven-development/SKILL.md b/skills/spec-driven-development/SKILL.md index 3922346..929dd0c 100644 --- a/skills/spec-driven-development/SKILL.md +++ b/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 From df5466380f8927ab3aca17bf240306ad3ac40cc6 Mon Sep 17 00:00:00 2001 From: li9292 Date: Tue, 12 May 2026 11:51:08 +0800 Subject: [PATCH 2/4] chore(#135): Empty scripts/ directories create inconsistency Fixes #135 Ref: https://github.com/addyosmani/agent-skills/issues/135 --- .auto-pr/SPEC.md | 40 ++++++++++++++++++++++++++++++++++++++++ .auto-pr/TODO.md | 22 ++++++++++++++++++++++ .auto-pr/issue.json | 1 + .auto-pr/target-repo.txt | 1 + AGENTS.md | 6 ++++-- CONTRIBUTING.md | 1 + docs/skill-anatomy.md | 5 +++++ 7 files changed, 74 insertions(+), 2 deletions(-) create mode 100644 .auto-pr/SPEC.md create mode 100644 .auto-pr/TODO.md create mode 100644 .auto-pr/issue.json create mode 100644 .auto-pr/target-repo.txt diff --git a/.auto-pr/SPEC.md b/.auto-pr/SPEC.md new file mode 100644 index 0000000..2213209 --- /dev/null +++ b/.auto-pr/SPEC.md @@ -0,0 +1,40 @@ +# Spec — Issue #135: Empty scripts/ directories create inconsistency + +> Source: https://github.com/addyosmani/agent-skills/issues/135 + +## Problem + +Contributor docs explain the required `SKILL.md` file and optional supporting files, but they never state plainly that a `scripts/` directory is optional and should only exist when a skill ships runnable helpers. That gap makes the template feel stricter than it is and encourages contributors to create empty `scripts/` directories just to match the example shape. + +## Acceptance criteria + +- [ ] Contributor docs explicitly say `scripts/` is optional and should only be added when the skill includes runnable helpers. +- [ ] Contributor docs explicitly discourage empty `scripts/` directories. +- [ ] The skill template in `AGENTS.md` makes the `Usage` / script section conditional rather than implied for every skill. + +## Approach + +Clarify the docs instead of deleting directories. Add a short explicit rule to `docs/skill-anatomy.md`, reinforce it in `CONTRIBUTING.md`, and update the `AGENTS.md` scaffold so contributors understand that script-backed skills and markdown-only skills are both valid patterns. + +## Files likely touched + +- `docs/skill-anatomy.md` — clarify that `scripts/` is optional and should not be empty +- `CONTRIBUTING.md` — reinforce the same rule in contributor-facing guidance +- `AGENTS.md` — adjust the skill template so the script usage section is optional + +## Risk / blast radius + +- **Scope**: small +- **Breaking**: no +- **Migration needed**: no + +## Test plan + +- **Unit**: n/a +- **Integration**: `rg` checks for explicit optional-scripts wording and `git diff --check` +- **Visual**: n/a + +## Out of scope + +- Removing or restructuring any existing skill directories +- Creating new scripts for markdown-only skills diff --git a/.auto-pr/TODO.md b/.auto-pr/TODO.md new file mode 100644 index 0000000..6d0b8ef --- /dev/null +++ b/.auto-pr/TODO.md @@ -0,0 +1,22 @@ +# TODO — Issue #135 + +## Setup + +- [x] Read the issue and current contributor docs +- [x] Confirm the repo no longer depends on empty `scripts/` directories being present + +## Docs update loop + +- [x] Clarify in `docs/skill-anatomy.md` that `scripts/` is optional and should not be created empty +- [x] Reinforce the same rule in `CONTRIBUTING.md` +- [x] Update the `AGENTS.md` template so script-backed usage examples are clearly optional + +## Verification + +- [x] `rg` confirms the docs explicitly describe optional `scripts/` usage +- [x] `git diff --check` passes +- [x] Self-review confirms the diff stays docs-only and scoped to the scripts-directory rule + +## Wrap-up + +- [ ] Commit, push, and open PR diff --git a/.auto-pr/issue.json b/.auto-pr/issue.json new file mode 100644 index 0000000..ee5e4c6 --- /dev/null +++ b/.auto-pr/issue.json @@ -0,0 +1 @@ +{"body":"Many skills have empty \\`scripts/\\` directories (e.g., \\`spec-driven-development\\`, \\`code-review-and-quality\\`). This creates confusion about when scripts are required vs optional.\n\n## Proposal\n\nEither:\n1. Remove empty \\`scripts/\\` directories for consistency, OR\n2. Add documentation in \\`docs/skill-anatomy.md\\` clarifying when scripts are needed vs optional\n\n## Affected skills\n\n- \\`spec-driven-development/\\` (empty scripts/)\n- \\`code-review-and-quality/\\` (empty scripts/)\n- (and potentially others)\n\nThis improves maintainability and reduces confusion for contributors.","labels":[],"number":135,"title":"Empty scripts/ directories create inconsistency","url":"https://github.com/addyosmani/agent-skills/issues/135"} diff --git a/.auto-pr/target-repo.txt b/.auto-pr/target-repo.txt new file mode 100644 index 0000000..87f6fba --- /dev/null +++ b/.auto-pr/target-repo.txt @@ -0,0 +1 @@ +addyosmani/agent-skills diff --git a/AGENTS.md b/AGENTS.md index 7b09470..004322c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,7 +106,7 @@ skills/ ```markdown --- name: {skill-name} -description: {One sentence describing when to use this skill. Include trigger phrases like "Deploy my app", "Check logs", etc.} +description: {One sentence describing what the skill does, followed by when to use it. Include trigger phrases like "Deploy my app" or "Check logs" when helpful.} --- # {Skill Title} @@ -117,7 +117,9 @@ description: {One sentence describing when to use this skill. Include trigger ph {Numbered list explaining the skill's workflow} -## 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] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d40f24b..8a5ed91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,6 +39,7 @@ New skills should generally follow the standard anatomy: - 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 diff --git a/docs/skill-anatomy.md b/docs/skill-anatomy.md index a71685a..572052c 100644 --- a/docs/skill-anatomy.md +++ b/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) @@ -100,6 +103,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. From de37fc6d3b304e7a987692f643e421efa077000f Mon Sep 17 00:00:00 2001 From: li9292 Date: Tue, 12 May 2026 11:53:55 +0800 Subject: [PATCH 3/4] chore: remove automation scratch files from PR --- .auto-pr/SPEC.md | 40 ---------------------------------------- .auto-pr/TODO.md | 22 ---------------------- .auto-pr/issue.json | 1 - .auto-pr/target-repo.txt | 1 - 4 files changed, 64 deletions(-) delete mode 100644 .auto-pr/SPEC.md delete mode 100644 .auto-pr/TODO.md delete mode 100644 .auto-pr/issue.json delete mode 100644 .auto-pr/target-repo.txt diff --git a/.auto-pr/SPEC.md b/.auto-pr/SPEC.md deleted file mode 100644 index 2213209..0000000 --- a/.auto-pr/SPEC.md +++ /dev/null @@ -1,40 +0,0 @@ -# Spec — Issue #135: Empty scripts/ directories create inconsistency - -> Source: https://github.com/addyosmani/agent-skills/issues/135 - -## Problem - -Contributor docs explain the required `SKILL.md` file and optional supporting files, but they never state plainly that a `scripts/` directory is optional and should only exist when a skill ships runnable helpers. That gap makes the template feel stricter than it is and encourages contributors to create empty `scripts/` directories just to match the example shape. - -## Acceptance criteria - -- [ ] Contributor docs explicitly say `scripts/` is optional and should only be added when the skill includes runnable helpers. -- [ ] Contributor docs explicitly discourage empty `scripts/` directories. -- [ ] The skill template in `AGENTS.md` makes the `Usage` / script section conditional rather than implied for every skill. - -## Approach - -Clarify the docs instead of deleting directories. Add a short explicit rule to `docs/skill-anatomy.md`, reinforce it in `CONTRIBUTING.md`, and update the `AGENTS.md` scaffold so contributors understand that script-backed skills and markdown-only skills are both valid patterns. - -## Files likely touched - -- `docs/skill-anatomy.md` — clarify that `scripts/` is optional and should not be empty -- `CONTRIBUTING.md` — reinforce the same rule in contributor-facing guidance -- `AGENTS.md` — adjust the skill template so the script usage section is optional - -## Risk / blast radius - -- **Scope**: small -- **Breaking**: no -- **Migration needed**: no - -## Test plan - -- **Unit**: n/a -- **Integration**: `rg` checks for explicit optional-scripts wording and `git diff --check` -- **Visual**: n/a - -## Out of scope - -- Removing or restructuring any existing skill directories -- Creating new scripts for markdown-only skills diff --git a/.auto-pr/TODO.md b/.auto-pr/TODO.md deleted file mode 100644 index 6d0b8ef..0000000 --- a/.auto-pr/TODO.md +++ /dev/null @@ -1,22 +0,0 @@ -# TODO — Issue #135 - -## Setup - -- [x] Read the issue and current contributor docs -- [x] Confirm the repo no longer depends on empty `scripts/` directories being present - -## Docs update loop - -- [x] Clarify in `docs/skill-anatomy.md` that `scripts/` is optional and should not be created empty -- [x] Reinforce the same rule in `CONTRIBUTING.md` -- [x] Update the `AGENTS.md` template so script-backed usage examples are clearly optional - -## Verification - -- [x] `rg` confirms the docs explicitly describe optional `scripts/` usage -- [x] `git diff --check` passes -- [x] Self-review confirms the diff stays docs-only and scoped to the scripts-directory rule - -## Wrap-up - -- [ ] Commit, push, and open PR diff --git a/.auto-pr/issue.json b/.auto-pr/issue.json deleted file mode 100644 index ee5e4c6..0000000 --- a/.auto-pr/issue.json +++ /dev/null @@ -1 +0,0 @@ -{"body":"Many skills have empty \\`scripts/\\` directories (e.g., \\`spec-driven-development\\`, \\`code-review-and-quality\\`). This creates confusion about when scripts are required vs optional.\n\n## Proposal\n\nEither:\n1. Remove empty \\`scripts/\\` directories for consistency, OR\n2. Add documentation in \\`docs/skill-anatomy.md\\` clarifying when scripts are needed vs optional\n\n## Affected skills\n\n- \\`spec-driven-development/\\` (empty scripts/)\n- \\`code-review-and-quality/\\` (empty scripts/)\n- (and potentially others)\n\nThis improves maintainability and reduces confusion for contributors.","labels":[],"number":135,"title":"Empty scripts/ directories create inconsistency","url":"https://github.com/addyosmani/agent-skills/issues/135"} diff --git a/.auto-pr/target-repo.txt b/.auto-pr/target-repo.txt deleted file mode 100644 index 87f6fba..0000000 --- a/.auto-pr/target-repo.txt +++ /dev/null @@ -1 +0,0 @@ -addyosmani/agent-skills From 4d277aa72e6620da792af7f5124f6cd4a73f3ece Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Tue, 12 May 2026 16:55:56 -0400 Subject: [PATCH 4/4] docs(skills): tighten frontmatter for idea-refine and browser-testing idea-refine: rewrite the description to follow the repository's documented "Use when..." trigger convention (AGENTS.md). The previous description was 135 characters, redundant, and used the skill name itself as the only trigger phrase, making it the only skill not aligned with how the other 21 skills self-describe. browser-testing-with-devtools: surface the Chrome DevTools MCP dependency at the top of the description and explicitly note the requirement, so agents that route by MCP availability can detect it without parsing the body. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- skills/browser-testing-with-devtools/SKILL.md | 2 +- skills/idea-refine/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/browser-testing-with-devtools/SKILL.md b/skills/browser-testing-with-devtools/SKILL.md index f2fb6bf..2af253b 100644 --- a/skills/browser-testing-with-devtools/SKILL.md +++ b/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 diff --git a/skills/idea-refine/SKILL.md b/skills/idea-refine/SKILL.md index 19554bf..30b1c80 100644 --- a/skills/idea-refine/SKILL.md +++ b/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