Skip to content

Commit 0aeecfe

Browse files
astefanutticlaude
astefanutti
and
claude
committed
Update ARCHITECTURE.md with correct strict mode semantics
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 8b8c14a commit 0aeecfe

1 file changed

Lines changed: 176 additions & 0 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Architecture
2+
3+
## Overview
4+
5+
The skills-registry is a centralized catalog that aggregates Claude Code plugins
6+
from multiple GitHub repositories into a single discoverable marketplace. It acts
7+
as an indirection layer: plugin source code lives in separate repos, while this
8+
registry provides the metadata and discovery mechanism.
9+
10+
```
11+
skills-registry
12+
┌──────────────────────────────────────────────────────┐
13+
│ │
14+
│ registry.yaml (source of truth) │
15+
│ │ │
16+
│ ├──► marketplace.json (Claude Code native) │
17+
│ ├──► catalog.md (human-readable) │
18+
│ │ │
19+
│ schema/ (validation) │
20+
│ scripts/ (automation) │
21+
│ .github/workflows/ (CI) │
22+
│ │
23+
└──────────────────────────────────────────────────────┘
24+
```
25+
26+
## Data Flow
27+
28+
```
29+
┌─────────────────┐
30+
│ registry.yaml │ Single source of truth
31+
│ │ (edited by humans)
32+
└────────┬────────┘
33+
│
34+
┌───────────┼───────────┐
35+
▼ ▼ ▼
36+
sync_marketplace generate validate
37+
.py _catalog _registry
38+
.py .py
39+
│ │ │
40+
▼ ▼ ▼
41+
marketplace.json catalog.md pass/fail
42+
(Claude Code) (docs) (CI gate)
43+
```
44+
45+
## File Structure
46+
47+
```
48+
skills-registry/
49+
├── registry.yaml # Source of truth
50+
├── .claude-plugin/
51+
│ └── marketplace.json # Generated — Claude Code reads this
52+
├── catalog.md # Generated — human-readable listing
53+
├── schema/
54+
│ └── registry.schema.json # JSON Schema for registry.yaml
55+
├── scripts/
56+
│ ├── validate_registry.py # Schema + structure validation
57+
│ ├── sync_marketplace.py # registry.yaml -> marketplace.json
58+
│ ├── generate_catalog.py # registry.yaml -> catalog.md
59+
│ └── check_versions.py # Poll plugin repos for version bumps
60+
├── .github/workflows/
61+
│ └── validate.yml # CI: validate + sync check
62+
├── README.md
63+
├── CONTRIBUTING.md
64+
└── LICENSE
65+
```
66+
67+
## Plugin Model
68+
69+
Each plugin entry in `registry.yaml` points to an external GitHub repo
70+
that contains the actual skills:
71+
72+
```
73+
registry.yaml External Repos
74+
┌──────────────┐
75+
│ plugins: │
76+
│ │ ┌────────────────────────────────┐
77+
│ rfe-creator ├───────►│ jwforres/rfe-creator │
78+
│ │ │ └─ .claude/skills/ │
79+
│ │ │ ├─ rfe.create/SKILL.md │
80+
│ │ │ ├─ rfe.review/SKILL.md │
81+
│ │ │ └─ ... │
82+
│ │ └────────────────────────────────┘
83+
│ │
84+
│ │ ┌────────────────────────────────┐
85+
│ assess-rfe ├───────►│ n1hility/assess-rfe │
86+
│ (strict: │ │ ├─ .claude-plugin/ │
87+
│ true) │ │ │ └─ plugin.json │
88+
│ │ │ └─ skills/ │
89+
│ │ │ ├─ assess-rfe/SKILL.md │
90+
│ │ │ └─ export-rubric/SKILL.md │
91+
│ │ └────────────────────────────────┘
92+
└──────────────┘
93+
```
94+
95+
### Strict vs Non-Strict Plugins
96+
97+
- **strict: true** (default) — `plugin.json` in the repo is the authority
98+
for component definitions. The marketplace entry can supplement it with
99+
additional components, and both sources are merged. Claude Code
100+
auto-discovers skills in default locations (`.claude/skills/`, `skills/`).
101+
Most plugins use this mode, even those without a `plugin.json`.
102+
103+
- **strict: false** — The marketplace entry is the entire plugin definition.
104+
If the repo also has a `plugin.json` that declares components, that is a
105+
conflict and the plugin fails to load. Use `skills_dir` to point to a
106+
non-default skills location. `skills_dir` is only valid with `strict: false`.
107+
108+
Note: `skills_dir` must not be specified without `strict: false`. The schema
109+
and validation scripts enforce this constraint.
110+
111+
### Dependencies
112+
113+
Plugins can declare `depends_on: [other-plugin]` to express inter-plugin
114+
dependencies within the registry. This is registry-level metadata only —
115+
it is not propagated to `marketplace.json` (Claude Code does not support
116+
dependency resolution).
117+
118+
## CI Pipeline
119+
120+
```
121+
push/PR to main
122+
│
123+
▼
124+
┌─────────────────────────────┐
125+
│ validate.yml │
126+
│ │
127+
│ 1. validate_registry.py │ Schema validation
128+
│ │ │
129+
│ 2. sync_marketplace.py │ Regenerate marketplace.json
130+
│ │ │
131+
│ 3. git diff --exit-code │ Fail if marketplace.json
132+
│ marketplace.json │ is out of sync
133+
│ │ │
134+
│ 4. generate_catalog.py │ Regenerate catalog.md
135+
│ │ │
136+
│ 5. git diff --exit-code │ Fail if catalog.md
137+
│ catalog.md │ is out of sync
138+
└─────────────────────────────┘
139+
```
140+
141+
CI does **not** auto-commit — it only verifies that the generated files
142+
match the registry. Contributors must run the scripts locally before pushing.
143+
144+
## How Claude Code Discovers Plugins
145+
146+
```
147+
Developer Claude Code GitHub
148+
│ │ │
149+
│ claude plugin marketplace │ │
150+
│ add opendatahub-io/ │ │
151+
│ skills-registry │ │
152+
│─────────────────────────────►│ │
153+
│ │ fetch marketplace.json │
154+
│ │─────────────────────────►│
155+
│ │◄─────────────────────────│
156+
│ │ │
157+
│ /plugin install │ │
158+
│ rfe-creator@opendatahub- │ │
159+
│ skills │ │
160+
│─────────────────────────────►│ clone source repo │
161+
│ │─────────────────────────►│
162+
│ │◄─────────────────────────│
163+
│ │ │
164+
│ /rfe.create │ │
165+
│─────────────────────────────►│ (runs skill locally) │
166+
│◄─────────────────────────────│ │
167+
```
168+
169+
## Adding a New Plugin
170+
171+
1. Add an entry to `registry.yaml`
172+
2. Run `python3 scripts/validate_registry.py`
173+
3. Run `python3 scripts/sync_marketplace.py`
174+
4. Run `python3 scripts/generate_catalog.py`
175+
5. Commit all changes and open a PR
176+
6. CI verifies everything is in sync

0 commit comments

Comments
 (0)