refactor: remove per-skill README.md mirrors (#302)#396
Merged
Conversation
Delete the 39 per-skill README.md files that mirrored their SKILL.md, merge the genuinely-unique content from the 7 outlier READMEs into SKILL.md (memory-bank-optional note, install prerequisite, experimental status), retarget plugin-level README skill tables and CREATE_PLUGIN.md to SKILL.md, and regenerate every plugin CATALOG.md. Phase 1 of aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
All verify-and-guard gates pass: check-markdown-links.js exits 0, zero plugins/*/skills/*/README.md remain, every affected skill dir still has SKILL.md, both asset READMEs and all plugin-level/framework READMEs are intact, sync-readme-counts.mjs --check exits 0, no CATALOG lists a per-skill README row, and 04-skill-generate scaffolds no per-skill README. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Both phases done and validation green (check-markdown-links.js and sync-readme-counts.mjs --check both exit 0). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
aidd-bot Bot
pushed a commit
that referenced
this pull request
Jul 7, 2026
* ci(framework): stop release-please re-tagging aidd-ui (#394) Remove the aidd-ui package from release-please-config.json. Its release-as: 0.1.0-alpha.0 pin forced the same version on every run, so any change touching aidd-ui made release-please retry the existing aidd-ui-v0.1.0-alpha.0 tag and fail (Validation Failed: already_exists). Dropping it from the config freezes aidd-ui at its current alpha while it is still a scaffold; re-add it with proper prerelease handling when it is ready to version. Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * ci(framework): drop the aidd-ui release-as pin, keep it consistent (#395) Restore the aidd-ui package block in release-please-config.json so it matches the other seven plugins (package-name + extra-files), but without the release-as: 0.1.0-alpha.0 pin. The pin forced the same version every run, retrying the existing aidd-ui-v0.1.0-alpha.0 tag and failing (already_exists). Supersedes the block removal in #394: aidd-ui stays release-managed like its siblings; the next change bumps it to a fresh version instead of colliding. Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * refactor: remove per-skill README.md mirrors (#302) (#396) * refactor: remove per-skill README.md mirrors, retarget to SKILL.md Delete the 39 per-skill README.md files that mirrored their SKILL.md, merge the genuinely-unique content from the 7 outlier READMEs into SKILL.md (memory-bank-optional note, install prerequisite, experimental status), retarget plugin-level README skill tables and CREATE_PLUGIN.md to SKILL.md, and regenerate every plugin CATALOG.md. Phase 1 of aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore: mark phase 2 done for remove-per-skill-readme plan All verify-and-guard gates pass: check-markdown-links.js exits 0, zero plugins/*/skills/*/README.md remain, every affected skill dir still has SKILL.md, both asset READMEs and all plugin-level/framework READMEs are intact, sync-readme-counts.mjs --check exits 0, no CATALOG lists a per-skill README row, and 04-skill-generate scaffolds no per-skill README. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore: mark remove-per-skill-readme plan implemented Both phases done and validation green (check-markdown-links.js and sync-readme-counts.mjs --check both exit 0). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore: mark remove-per-skill-readme plan reviewed --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * ci(deps): bump github/codeql-action/init from 4.36.2 to 4.36.3 (#398) Bumps [github/codeql-action/init](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@8aad20d...54f647b) --- updated-dependencies: - dependency-name: github/codeql-action/init dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(deps-dev): bump js-yaml from 5.0.0 to 5.2.1 (#401) Bumps [js-yaml](https://github.com/nodeca/js-yaml) from 5.0.0 to 5.2.1. - [Changelog](https://github.com/nodeca/js-yaml/blob/master/CHANGELOG.md) - [Commits](nodeca/js-yaml@5.0.0...5.2.1) --- updated-dependencies: - dependency-name: js-yaml dependency-version: 5.2.1 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * ci(deps): bump github/codeql-action/autobuild from 4.36.2 to 4.36.3 (#399) Bumps [github/codeql-action/autobuild](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@8aad20d...54f647b) --- updated-dependencies: - dependency-name: github/codeql-action/autobuild dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * ci(deps): bump github/codeql-action/analyze from 4.36.2 to 4.36.3 (#400) Bumps [github/codeql-action/analyze](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@8aad20d...54f647b) --- updated-dependencies: - dependency-name: github/codeql-action/analyze dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(deps-dev): bump @commitlint/cli from 21.0.2 to 21.2.0 Bumps [@commitlint/cli](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/cli) from 21.0.2 to 21.2.0. - [Release notes](https://github.com/conventional-changelog/commitlint/releases) - [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/cli/CHANGELOG.md) - [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.0/@commitlint/cli) --- updated-dependencies: - dependency-name: "@commitlint/cli" dependency-version: 21.2.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 What & why
Each skill shipped a
README.mdthat ~100% duplicated itsSKILL.md(when-to-use, actions table, invocation, output). Per the 2026-06-18 roadmap decision, the mirror is redundant — people read theSKILL.md. This removes all 39 per-skill READMEs and repoints navigation atSKILL.md.🛠️ How it works
README.md→SKILL.mdis fragile cross-OS and rendersSKILL.md's raw YAML frontmatter on GitHub folder-browse. Issue refactor: remove per-skill README.md (duplicates SKILL.md) #302 explicitly accepts clean removal, so the 39plugins/*/skills/*/README.mdare deleted outright. Asset READMEs (02-project-memory/assets/**), the 7 plugin-level READMEs, and the top-level README are untouched.plugins/*/README.mdand the links indocs/CREATE_PLUGIN.mdnow point atSKILL.md.CREATE_PLUGIN.mdalso drops the structure-diagram line and section that used to prescribe a per-skill README, so the convention won't reintroduce them.plugins/*/CATALOG.mdis auto-generated byscripts/summarize-markdown.js(pre-commit via lefthook); regenerating drops the README rows with zero drift.00-onboard,01-hello,00-repo-initcarried prose absent from theirSKILL.md(e.g.01-hello'sclaude --plugin-dirinstall prereq) — folded into theSKILL.mdfirst. The other 4 breadcrumb-less READMEs were pure mirrors.04-skill-generatescaffoldsSKILL.md+ actions only, so newly generated skills won't recreate the mirror.Plan and review live at
aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/.🧪 How to verify
node scripts/check-markdown-links.js→0 broken in 364 files, exit 0 (no link resolves to a deleted README).node scripts/sync-readme-counts.mjs --check→ exit 0.find plugins -type f -name README.md -path '*/skills/*' -not -path '*/assets/*'→ empty; every affected skill dir still hasSKILL.md.SKILL.mdin the file list; plugin README Skills tables click through to it.🔗 Linked issue
Closes #302