addyosmani / addyosmani/agent-skills

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

オープン
#539 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
主要言語
JavaScript
スター
94.1k
フォーク
10k
平均マージ
3日 15時間
マージ済み PR(30日)
23

説明

## 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.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

Inspect `scripts/validate-skills.js` first, since the proposal suggests adding a `--check` mode there or creating `scripts/sync-catalog.js` to reuse existing validator patterns. Use `skills/*/SKILL.md` as the canonical input and compare it against the listed outputs in `README.md`, `CLAUDE.md`, and `.github/ISSUE_TEMPLATE/skill-gap.yml` (plus related docs references in issue). Run the updated validator/check script locally and define done as an implemented mode that reports catalog drift and can pass with zero mismatches for tracked surfaces.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
javascript
領域
documentation, tooling
issue の種類
機能追加
難易度
3/5
見積もり時間
1〜2日
活発さ
活発
明瞭さ
おおむね明確
初心者へのやさしさ
70/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。