|
| 1 | +# Syncing this skill into a registry |
| 2 | + |
| 3 | +Third-party skill registries vendor this skill into their own repositories. Every rule below |
| 4 | +exists because a registry had to patch the vendored copy at least once; upstream now holds it |
| 5 | +in CI so a sync stays a file copy instead of a copy plus a patch that has to be re-applied |
| 6 | +every release. |
| 7 | + |
| 8 | +If your registry needs an edit that is not covered here, please |
| 9 | +[open an issue](https://github.com/ImagingDataCommons/imaging-data-commons-skill/issues/new/choose) |
| 10 | +rather than carrying the patch — the fix belongs upstream. |
| 11 | + |
| 12 | +## Take the release attachment |
| 13 | + |
| 14 | +Every release carries `imaging-data-commons-<version>.zip`, and that attachment *is* the |
| 15 | +bundle — nothing in it is optional: |
| 16 | + |
| 17 | +```bash |
| 18 | +gh release download vX.Y.Z -R ImagingDataCommons/imaging-data-commons-skill -p '*.zip' |
| 19 | +``` |
| 20 | + |
| 21 | +``` |
| 22 | +SKILL.md the always-loaded file |
| 23 | +references/ topical guides, loaded on demand |
| 24 | +scripts/ check_version.py, the startup version check |
| 25 | +``` |
| 26 | + |
| 27 | +Vendor `scripts/` along with the other two. It is the skill's first step — `python |
| 28 | +scripts/check_version.py` reports whether `idc-index` is installed and current enough, prints |
| 29 | +the install command for the interpreter that ran it, and exits non-zero so the agent stops |
| 30 | +rather than querying a stale index. Registries that require a test suite for any skill |
| 31 | +shipping `scripts/` should see *Tests* below. |
| 32 | + |
| 33 | +Copying from a checkout works too, but then getting the path list right is on you, and `main` |
| 34 | +can sit between releases. `README.md`, `USAGE.md`, `CHANGELOG.md`, `tests/`, and `.github/` |
| 35 | +are repository infrastructure and are deliberately absent from the zip: `USAGE.md` documents |
| 36 | +loading the skill from this repository, which is not how a registry's users will get it. |
| 37 | + |
| 38 | +## What upstream guarantees |
| 39 | + |
| 40 | +| Guarantee | Held by | |
| 41 | +|---|---| |
| 42 | +| `SKILL.md` is at most 500 lines | `tests/test_structure.py::TestLineBudget` | |
| 43 | +| `metadata` frontmatter entries are indented exactly two spaces | `TestFrontmatter::test_metadata_scalars_are_indented_two_spaces` | |
| 44 | +| `metadata.version` is `MAJOR.MINOR.PATCH` | `TestFrontmatter::test_version_is_semver` | |
| 45 | +| Frontmatter uses only Agent Skills top-level keys (`name`, `description`, `license`, `metadata`) | Agent Skills spec | |
| 46 | +| No hardcoded `pip` / `uv` / `conda` / `poetry` install command in `SKILL.md` or `references/` | `TestInstallCommands` | |
| 47 | +| Every `references/` and `scripts/` path the docs name resolves, and no guide is unreachable | `TestReferenceLinks` | |
| 48 | +| The bundled script never shells out to an installer, never calls `eval` / `exec` / `os.system`, and never overrides PEP 668 | `tests/test_check_version.py::TestNeverInstalls` | |
| 49 | +| The bundled script imports without network access, `idc-index`, or any third-party package | `tests/test_check_version.py` | |
| 50 | +| No tests, fixtures, or bytecode inside the three vendored paths | the release zip is built from those paths alone | |
| 51 | + |
| 52 | +Two-space indentation and the absence of installer commands are the two that broke a |
| 53 | +registry's conformance gate in practice, so they are pinned rather than left to style. |
| 54 | + |
| 55 | +For a security triage: `check_version.py` is standard library only, takes no arguments, and |
| 56 | +its only network access is two public JSON endpoints — the PyPI project page for `idc-index` |
| 57 | +and this repository's GitHub releases API — read with `urllib` to print update notices, both |
| 58 | +best-effort and skipped when unreachable. It reads no environment variables and no |
| 59 | +credentials. |
| 60 | + |
| 61 | +## Version numbering |
| 62 | + |
| 63 | +Registries that maintain their own skill version should set `metadata.version` to theirs and |
| 64 | +record ours alongside it: |
| 65 | + |
| 66 | +```yaml |
| 67 | +metadata: |
| 68 | + version: "1.5" # the registry's numbering |
| 69 | + source-skill-version: 1.8.1 # the upstream release this copy came from |
| 70 | +``` |
| 71 | +
|
| 72 | +`scripts/check_version.py` pins `SKILL_VERSION` to the upstream release and compares it |
| 73 | +against this repository's GitHub releases to notify users when a newer skill is available. A |
| 74 | +test asserting that the script and the frontmatter agree must therefore read |
| 75 | +`source-skill-version`, not `version`, in a renumbered copy. |
| 76 | + |
| 77 | +## Tests |
| 78 | + |
| 79 | +Registries that require a test suite for a skill shipping `scripts/` should copy |
| 80 | +`tests/test_check_version.py` out of this repository. It is written to be vendored: offline, |
| 81 | +standard library plus pytest, no `idc-index` install, and it runs with nothing else present. |
| 82 | +Only the two path constants at the top change — plus the frontmatter assertion above, if you |
| 83 | +renumber. |
| 84 | + |
| 85 | +Do not vendor `tests/test_snippets.py`, `test_rest_api.py`, `test_mcp_server.py`, or |
| 86 | +`test_bq_snippets.py`. They need `idc-index`, live IDC endpoints, and (for BigQuery) GCP |
| 87 | +credentials, and they already run here on every pull request. |
| 88 | + |
| 89 | +## One sync, step by step |
| 90 | + |
| 91 | +1. Download the release attachment and unpack it. |
| 92 | +2. **Replace the whole skill directory**, rather than merging file by file. Guides do get |
| 93 | + removed: content moves between them when `SKILL.md` is reduced, and a stale guide left |
| 94 | + behind means the same material in two places. |
| 95 | +3. Re-copy `tests/test_check_version.py` and adjust its path constants. |
| 96 | +4. Renumber the frontmatter if your registry does that, keeping `source-skill-version`. |
| 97 | +5. Run your validators, then check `CHANGELOG.md` for the `idc-index` pin and IDC data |
| 98 | + version this release was tested against — both also appear in the frontmatter. |
| 99 | +6. **Say what was removed** in the sync pull request. A deletion is the one part of a |
| 100 | + wholesale copy that is not self-explanatory. |
0 commit comments