addyosmani / addyosmani/agent-skills

Generate the skill catalog instead of hand-maintaining it across surfaces

Aperta
#539 1 commento 0 reazioni 0 assegnatari Vedi su GitHub
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.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.