addyosmani / addyosmani/agent-skills
Generate the skill catalog instead of hand-maintaining it across surfaces
- Lingua principale
- JavaScript
- Stelle
- 93.8k
- Fork
- 10k
- Merge medio
- 3g 15h
- PR unite (30g)
- 23
Descrizione
## Summary
The skill list is maintained by hand across several tracked files, and nothing in CI checks that those copies agree with `skills/`. Adding a skill means remembering every surface. There is currently drift on `main` because one of those surfaces was missed.
Proposal: derive the catalog surfaces from `skills/` with a script that has a `--check` mode, and run that check in CI. Every existing script under `scripts/` validates; none generates. This is the first case where generating is cheaper than remembering.
## Current drift on `main`
`constraint-driven-development` shipped in #472 (`2ce8d47`, 28 Aug) and is missing from two places:
| Surface | State |
|---|---|
| `README.md` | present |
| `skills/using-agent-skills/SKILL.md` | present |
| `CLAUDE.md`, "Skills by Phase" (line 23) | **missing** |
| `.github/ISSUE_TEMPLATE/skill-gap.yml` dropdown | **missing** |
The issue-form gap has a user-visible consequence: someone hitting bad guidance from `constraint-driven-development` today cannot select it when filing a skill-gap report. The form landed in `b68f553` (19 Jul), the skill five weeks later, and nothing connected them.
## Why this is a process gap and not one contributor's slip
#472 was not careless. It updated ten files across the catalog:
```
README.md
skills/using-agent-skills/SKILL.md
docs/adoption-guide.md
docs/codex-setup.md
docs/commandcode-setup.md
docs/comparison.md
evals/cases/constraint-driven-development.json
commands/constraints.toml
.claude/commands/constraints.md
.gemini/commands/constraints.toml
```
It still missed two. Ten hand-updated surfaces per skill is past the point where care is the right mechanism, and the number grows with every runtime integration the repo adds (#530, #355, #439, #477 are all open requests that would add more).
## Sketch
`scripts/sync-catalog.js`, reading `skills/*/SKILL.md` frontmatter as the single source of truth:
- `--check` (CI): exit non-zero listing any surface whose skill set disagrees with `skills/`
- `--write` (local): update the generated regions in place
Generated regions marked with comment fences so hand-written prose around them is untouched, for example `` / `` in Markdown and the equivalent in the issue form's `options:` block.
Starting with `--check` alone would already have caught this, and is the smaller change if writing into tracked docs feels too invasive for a first cut.
## Open questions
1. Which surfaces should be authoritative-generated versus merely checked? `README.md` prose probably wants a human touch; the issue-form dropdown is pure data and could be fully generated.
2. Does `CLAUDE.md`'s phase grouping belong in frontmatter (a `phase:` field) or in a small mapping file the script reads? The phase is currently implicit in prose.
3. Should this live in an existing validator rather than a new script? `validate-skills.js` already walks `skills/`, so the check could be a mode there instead.
## Not overlapping with existing work
#137 covers markdown formatting consistency (`markdownlint`, heading levels, list markers), which is orthogonal to catalog membership. #511 is about doc/code drift as guidance inside the `documentation-and-adrs` skill, not this repo's own catalog. I did not find an open PR touching this.
## Credit
The generate-plus-`--check` pattern is borrowed from [affaan-m/ecc](https://github.com/affaan-m/ecc), which ships `catalog:check` / `catalog:sync` and `command-registry:generate --check` for the same problem at a larger catalog size. The idea is theirs; no code is proposed to be copied.
Happy to open a PR for the `--check` half if the direction is right. Given that `scripts/` is collision-prone with in-flight work (#428, #444, #517 all touch validators), I would rather agree the shape here first.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.