Skip to content

Commit 59fa8b5

Browse files
mnriemmnriem
authored
Move community extensions table from README to docs site (#2560)
* Add Agent Governance extension to community catalog Add agent-governance extension submitted by @bigsmartben to: - extensions/catalog.community.json (alphabetical order) - README.md community extensions table Closes #2552 * Move community extensions table from README to docs site - Create docs/community/extensions.md with full extensions table - Replace ~120-line table in README.md with summary + link to docs site - Add Extensions entry to docs/toc.yml under Community - Update add-community-extension SKILL.md references
1 parent def1a05 commit 59fa8b5

5 files changed

Lines changed: 299 additions & 120 deletions

File tree

‎.github/skills/add-community-extension/SKILL.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
name: add-community-extension
3+
description: 'Add a community extension to the Spec Kit catalog from a GitHub issue submission. USE FOR: processing extension submission issues, validating catalog entries, updating catalog.community.json and docs/community/extensions.md, creating PRs. DO NOT USE FOR: creating new extensions from scratch, or first-party extension work.'
4+
argument-hint: 'GitHub issue URL or number for the extension submission'
5+
---
6+
7+
# Add Community Extension
8+
9+
Process an extension submission issue and add or update it in the community catalog.
10+
11+
## When to Use
12+
13+
- A new `[Extension]` submission issue is filed
14+
- An existing extension submits an update issue (new version, changed metadata)
15+
- You need to add or update a community extension in `extensions/catalog.community.json` and `docs/community/extensions.md`
16+
17+
## Procedure
18+
19+
### 1. Fetch the submission issue
20+
21+
Read the GitHub issue to extract all metadata:
22+
- Extension ID, name, version, description, author
23+
- Repository URL, download URL, homepage, documentation, changelog
24+
- License, required spec-kit version, optional tool dependencies
25+
- Number of commands and hooks
26+
- Tags
27+
28+
### 2. Validate against publishing rules
29+
30+
Check **all** of the following (per `extensions/EXTENSION-PUBLISHING-GUIDE.md`):
31+
32+
| Check | How |
33+
|-------|-----|
34+
| Repository exists and is public | Fetch the repository URL |
35+
| `extension.yml` manifest present | Confirm in repo file listing |
36+
| README.md present | Confirm in repo file listing |
37+
| LICENSE file present | Confirm in repo file listing |
38+
| GitHub release exists matching version | Check releases on the repo page |
39+
| Download URL is accessible | Verify it follows `archive/refs/tags/vX.Y.Z.zip` pattern and release exists |
40+
| Extension ID is lowercase-with-hyphens only | Regex: `^[a-z][a-z0-9-]*$` |
41+
| Version follows semver | Format: `X.Y.Z` |
42+
| Submission checklists are all checked | Confirm in issue body |
43+
44+
### 3. Determine if this is an add or update
45+
46+
Search `extensions/catalog.community.json` for the extension ID.
47+
48+
- **Not found** → this is a **new addition**. Proceed to step 4.
49+
- **Found** → this is an **update**. Proceed to step 4 but replace the existing entry in-place instead of inserting.
50+
51+
### 4. Add or update `extensions/catalog.community.json`
52+
53+
**New extension:** Insert the entry in **alphabetical order** by extension ID.
54+
55+
**Update:** Replace the existing entry in-place. Update only the fields that changed (typically `version`, `download_url`, `description`, `provides`, `requires`, `tags`, `updated_at`). Preserve `created_at` and `downloads`/`stars` from the existing entry.
56+
57+
Use the existing entries as the format template. Required fields:
58+
59+
```json
60+
{
61+
"<id>": {
62+
"name": "<name>",
63+
"id": "<id>",
64+
"description": "<description>",
65+
"author": "<author>",
66+
"version": "<version>",
67+
"download_url": "<download_url>",
68+
"repository": "<repository>",
69+
"homepage": "<homepage>",
70+
"documentation": "<documentation>",
71+
"changelog": "<changelog>",
72+
"license": "<license>",
73+
"requires": {
74+
"speckit_version": "<speckit_version>"
75+
},
76+
"provides": {
77+
"commands": <N>,
78+
"hooks": <N>
79+
},
80+
"tags": ["<tag1>", "<tag2>"],
81+
"verified": false,
82+
"downloads": 0,
83+
"stars": 0,
84+
"created_at": "<today>T00:00:00Z",
85+
"updated_at": "<today>T00:00:00Z"
86+
}
87+
}
88+
```
89+
90+
If the extension has optional tool dependencies, add a `"tools"` array inside `"requires"`:
91+
92+
```json
93+
"tools": [{ "name": "<tool>", "required": false }]
94+
```
95+
96+
Also update the top-level `"updated_at"` timestamp in the catalog.
97+
98+
After editing, **validate the JSON** by running:
99+
100+
```bash
101+
python3 -c "import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')"
102+
```
103+
104+
### 5. Add or update `docs/community/extensions.md` community extensions table
105+
106+
**New extension:** Insert a new row into the `# Community Extensions` table in **alphabetical order** by extension name.
107+
108+
**Update:** Find the existing row and update the description or other changed fields in-place.
109+
110+
Determine the category and effect from the extension's behavior:
111+
112+
```
113+
| <Name> | <Description> | `<category>` | <Effect> | [<repo-name>](<repository-url>) |
114+
```
115+
116+
**Category** — one of: `docs`, `code`, `process`, `integration`, `visibility`
117+
**Effect** — `Read-only` (produces reports only) or `Read+Write` (modifies project files)
118+
119+
### 6. Commit, push, and open PR
120+
121+
Use `add-` for new extensions, `update-` for updates:
122+
123+
```bash
124+
# New extension
125+
git checkout -b add-<extension-id>-extension
126+
127+
# Update
128+
git checkout -b update-<extension-id>-extension
129+
```
130+
131+
```bash
132+
git add extensions/catalog.community.json docs/community/extensions.md
133+
134+
# New extension
135+
git commit -m "Add <Name> extension to community catalog
136+
137+
Add <id> extension submitted by @<issue-author> to:
138+
- extensions/catalog.community.json (alphabetical order)
139+
- docs/community/extensions.md community extensions table
140+
141+
Closes #<issue-number>"
142+
143+
# Update
144+
git commit -m "Update <Name> extension to v<version>
145+
146+
Update <id> extension submitted by @<issue-author>:
147+
- extensions/catalog.community.json (version, download_url, etc.)
148+
- docs/community/extensions.md community extensions table
149+
150+
Closes #<issue-number>"
151+
152+
git push origin <branch-name>
153+
```
154+
155+
Then create a PR to `upstream` (`github/spec-kit`) with:
156+
- **Title:** `Add <Name> extension to community catalog` (or `Update <Name> extension to v<version>`)
157+
- **Body:** Include validation summary, `Closes #<issue-number>`, and `cc @<issue-author>`
158+
- **Head:** `<fork-owner>:<branch-name>`
159+
- **Base:** `main`
160+
161+
## Common Pitfalls
162+
163+
- **Alphabetical order matters** — entries must be sorted by ID in the JSON and by name in the docs table.
164+
- **Don't forget the catalog `updated_at`** — the top-level timestamp in `catalog.community.json` must be refreshed.
165+
- **Validate JSON after editing** — a trailing comma or missing brace will break the catalog.
166+
- **Use `Closes` not `Fixes`** — `Closes #N` is the correct keyword for submission issues.
167+
- **Match the proposed entry but verify** — the issue may include a proposed JSON block, but always validate field values against the actual repository state.
168+
- **Preserve `created_at` on updates** — keep the original `created_at` value; only change `updated_at`.
169+
- **Preserve `downloads` and `stars` on updates** — these reflect usage metrics and must not be reset.

0 commit comments

Comments
 (0)