addyosmani / addyosmani/agent-skills

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

Đang mở
#539 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
JavaScript
Star
94.1k
Fork
10k
Merge trung bình
3 ngày 15 giờ
Pull request đã merge (30 ngày)
23

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
javascript
Lĩnh vực
documentation, tooling
Loại issue
Tính năng
Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
70/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.