Skill Registry Hub¶

1. What a hub is¶

A hub is a Git repository that:

Stores skills as directories, each containing a SKILL.md
Runs a CI pipeline on every push that validates each skill and regenerates index.json
Publishes index.json at a stable URL (GitHub Pages, raw.githubusercontent.com, S3, etc.)

An agent references one or more hub URLs. It never needs to know the internal structure of the repo — only the index.json contract and, optionally, the Git URL for cloning.

2. Hub repository structure¶

my-hub/
├── .github/
│   └── workflows/
│       └── publish.yml     # validate + generate index.json on push
├── skills/
│   ├── python-developer/
│   │   └── SKILL.md
│   ├── pdf-processing/
│   │   ├── SKILL.md
│   │   └── scripts/
│   └── ...
└── index.json              # generated by CI, committed or published to Pages

CI pipeline responsibilities¶

Validate each SKILL.md against the skill spec
Reject skills that fail validation — the push fails, index.json is not updated
Generate index.json from all valid skills' frontmatter
Publish index.json to the hub's stable URL

index.json is always a snapshot of validated skills only.

Implementation: The agentctl CLI provides hub validate and hub generate commands for CI pipeline integration.

index.json schema¶

Formal schema: schemas/skills-index.json

Naming convention: Use index.json for skill-only repos. If a repo contains both skills and docs, use skills.json and docs.json to avoid conflicts.

{
  "hub_id": "my-hub",
  "generated_at": "2025-07-01T12:00:00Z",
  "skills": [
    {
      "slug": "python-developer",
      "name": "python-developer",
      "description": "Expert Python developer with modern practices.",
      "version": "1.2.0",
      "compatibility": "Requires Python 3.10+, uv package manager",
      "license": "MIT",
      "git_url": "https://github.com/myorg/my-hub",
      "path": "skills/python-developer",
      "commit": "abc123"
    }
  ]
}

git_url + path + commit are sufficient to fetch the skill without a separate archive.

3. Multi-hub configuration¶

An agent holds a list of hub sources:

[
  {
    "id": "official-hub",
    "index_url": "https://myorg.github.io/official-hub/index.json",
    "git_url": "https://github.com/myorg/official-hub",
    "enabled": true,
    "ttl_hours": 6
  },
  {
    "id": "private-hub",
    "index_url": "https://raw.githubusercontent.com/myorg/private-skills/main/index.json",
    "git_url": "https://github.com/myorg/private-skills",
    "enabled": true,
    "ttl_hours": 1
  }
]

Adding a new hub = adding one entry. No code changes needed.

4. Two fetch modes per hub¶

4.1 Index fetch (for search)¶

GET index_url → parse → cache locally (TTL)

Fast, no clone. The cached index.json is the search corpus.

4.2 Git clone (for install and offline use)¶

git clone git_url → ~/.cache/<agent>/hubs/<hub_id>/
git sparse-checkout set skills/<slug>

Sparse checkout means only the target skill directory is downloaded. For subsequent installs from the same hub, the local clone is already present — just git fetch + sparse checkout.

Mode selection: - Search → index fetch (fast, no disk) - Install → sparse clone (exact files needed) - Offline → fall back to local clone if index cache is stale and network unavailable

5. index.json as the contract¶

The index.json is the only interface between a hub and an agent. This means:

Any Git repo that publishes a valid index.json is a hub — regardless of internal layout
The CI pipeline is the trust boundary: it validates and normalizes skill metadata
An agent consuming the hub never parses raw SKILL.md files from the repo directly

This also means existing skill repos (e.g. clawdhub, AgentSkills example repo) can become compatible hubs by adding a CI step that generates index.json in this schema.

6. Search across hubs¶

Search fetches the cached index from each enabled hub and scores entries by matching against name and description fields. Results from all hubs are merged and ranked together.

For a unified local + hub search: local results (already installed) rank higher, then hub results not yet installed, deduplicated by slug within each hub.

7. Install and lock file¶

Installing a skill from a hub:

Look up the entry in the cached index
Sparse-clone the hub repo (or reuse existing clone), checkout path at commit
Copy skill directory to the agent's local skills folder
Write a lock entry

Lock entry schema:

{
  "official-hub:python-developer": {
    "hub_id": "official-hub",
    "slug": "python-developer",
    "version": "1.2.0",
    "commit": "abc123",
    "installed_path": "skills/python-developer",
    "installed_at": "2025-07-01T12:00:00Z"
  }
}

hub_id:slug is the deduplication key. Two hubs can both provide a python-developer skill and they coexist as separate lock entries with separate install paths.

Update = compare version in lock vs current index.json; re-install if newer.

8. Security¶

Validated at source — index.json only contains skills that passed CI. The agent trusts the hub operator's CI, not individual skill authors.
Git integrity — sparse clone over HTTPS; Git object hashing ensures file integrity.
Compatibility check — the agent reads the compatibility field and can warn users about missing requirements before installation.
No auto-install — the agent can suggest a hub install, but execution requires explicit user confirmation.
Pinned by commit — the lock stores the exact commit; updates are explicit.
Lifecycle approval — if a skill includes lifecycle.yaml, all install/update/uninstall commands require user approval.

9. Setting up a hub¶

Create a Git repo with a skills/ directory
Add skills as skills/<slug>/SKILL.md (optionally with lifecycle.yaml)
Add a CI workflow that validates skills and generates index.json
Publish index.json at a stable URL

The CI validator should check:

Required frontmatter fields (name, description)
Directory name matches name field
Valid YAML frontmatter syntax
Optional: lifecycle.yaml syntax if present

Implementation: Use agentctl hub validate to validate skills and agentctl hub generate to create the index.json file.