.json` or `.json`: one catalog item with `$schema`, `kind` and `specVersion` added (section 7.6).
- **Entry point**: A published file that a client finds by a fixed path rather than by a link (section 5).
- **External entry**: An input B marketplace entry whose source is remote. It is listed in the catalog but never fetched or packaged (section 7.7).
- **Generator**: Software that reads an input tree and parameters and writes the published files. A conforming generator meets section 16.1.
- **Host**: An application that installs plugins or skills. This profile covers Claude Code, Codex, Grok Build, Antigravity and Gemini CLI, plus clients of Agent Skills discovery.
- **Host package**: An archive or tree in a host-specific layout, produced only when requested (Annex A).
- **Install prompt**: Generated text a user can paste into their own agent to install one plugin or skill with the host's own commands (section 12).
- **Lock**: The record, kept in the source repository and never published, of every archive published under a versioned path and its digest (section 11.2).
- **Plugin** (from Claude Code plugin reference): A directory in the Claude Code plugin layout: an optional `.claude-plugin/plugin.json` plus component folders such as `skills/`, `agents/`, `commands/` and `hooks/`.
- **Plugin archive**: The archive of a whole plugin, with the plugin root at the top, used as a Claude Code archive source (section 10.1).
- **Site**: The static website the files are published on. Its origin is the scheme, host and port of `siteUrl`.
- **Skill** (from Agent Skills): A directory holding a `SKILL.md` file and any supporting files.
- **Skill archive** (from Agent Skills discovery 0.2.0): The archive of one skill with `SKILL.md` at the top, as Agent Skills discovery 0.2.0 requires (section 10.1).
- **Support level**: One of native, partial or none, saying how much of a plugin works on a host (section 7.5).
- **Well-known URI** (from RFC 8615): A URI whose path starts with `/.well-known/`, reserved for names registered with IANA.
- **Yank**: To withdraw one published version: it leaves every published document and its archives stop being served, and the lock keeps the reason (section 11.4).
In paths, `
` a plugin name, ` .json` | one plugin entry | 7.6 |
| ` / .zip` | plugin archive | 10.1 |
| ` / . /` |
| `entryUrl` | the URL of the plugin's entry document |
Each hook item is one handler of `hooks/hooks.json`, visiting events in sorted order, then matcher groups and handlers in file order. It has `event`, `type`, and when present in the input `matcher`, `command`, `url` and `timeout`.
Each MCP server item has `name`, `env` (the sorted names of its environment variables) and, when present, `command` or `url`. A generator MUST NOT copy environment variable values, headers or arguments that could hold credentials.
### 7.4. Skill items
| Member | Content |
|---|---|
| `name`, `description` | from the skill's `SKILL.md` |
| `version`, `license` | from the plugin that holds the skill |
| `plugin` | the name of that plugin |
| `files` | every member of the skill archive, as in section 7.3 |
| `packages` | `skillArchive` and `claudeAiUpload` (section 10.1) |
| `install` | `prompts`, with at least `agent-skills` (section 12) |
| `pageUrl` | `siteUrl` + `pages` + ` /skills/ .json`; for every skill item, ` ` | `application/zip` | the plugin archive | `description`, `digest`, `version`, profile extension with role `claude-plugin-archive` |
| the catalog | `urn:air: entry` or ` / .zip` | the plugin root (`.claude-plugin/`, `skills/`, ...) | Claude Code `archive` source |
| Skill archive | `/.well-known/agent-skills/ @ " plugin, version @ .html`, `head-skill- /
.claude-plugin/plugin.json input
plugin.json Agent Plugins 1.0 (Codex)
.antigravity-plugin/plugin.json Antigravity; takes precedence over plugin.json
gemini-extension.json Gemini CLI
skills/ agents/ input, shared
commands/*.md input (Claude Code)
commands/*.toml Gemini CLI
hooks/hooks.json input (Claude Code event names)
hooks.json Antigravity
.mcp.json input (Claude Code)
mcp.json Agent Plugins
mcp_config.json Antigravity
```
Codex skips `github` and `archive` sources, so the tree's marketplace files use relative sources only. The URL-mode marketplace of section 8.3 is a different file with a different name.
### A.2. Field mapping
| Input (`.claude-plugin/plugin.json`) | Agent Plugins / Codex | Antigravity | Gemini CLI |
|---|---|---|---|
| `name` | `name` | `name` | `name` |
| `displayName` | `extensions["com.openai"].interface.displayName` | `displayName` | not carried |
| `version`, `description` | same | same | same |
| `author`, `homepage`, `repository`, `license`, `keywords` | same | same | not carried |
| `skills/` | `skills/` | `skills/` | `skills/` |
| `agents/*.md` | not carried | `agents/` | `agents/*.md` (preview) |
| `commands/*.md` | not carried | not carried | converted to `commands/*.toml` |
| `hooks/hooks.json` | `extensions["com.openai"].hooks` | root `hooks.json` | `hooks/hooks.json`, renamed events, timeouts in ms |
| `.mcp.json` | `mcp.json` | `mcp_config.json`, servers named ` _ / .antigravity.zip` | the plugin root with the Antigravity files |
| Gemini CLI | ` / .gemini.zip` | the plugin root with the Gemini CLI files |
| Bundle | ` ` for Antigravity, `gemini extensions install ./ ` for Gemini CLI, and `--plugin-dir ./market/plugins/ ` for Grok Build. Exact templates will be defined once each path has been tested against the host.
## Annex B. Example (informative)
A minimal catalog for one skill-only plugin; the conformance suite has complete, byte-exact examples.
```json
{
"$schema": "https://static-agent-marketplace.org/schemas/draft/catalog.schema.json",
"entryPoints": {
"aiCatalog": "https://plugins.example.com/.well-known/ai-catalog.json",
"catalog": "https://plugins.example.com/.agent-marketplace/catalog.json",
"claudeMarketplace": "https://plugins.example.com/.claude-plugin/marketplace.json",
"llmsTxt": "https://plugins.example.com/llms.txt",
"sha256sums": "https://plugins.example.com/.agent-marketplace/SHA256SUMS"
},
"external": [],
"marketplace": {
"name": "example-market",
"owner": {
"name": "Example Publisher"
},
"url": "https://plugins.example.com/"
},
"plugins": [],
"skills": [],
"specVersion": "0.1.0-draft"
}
```
## Annex C. References
Normative:
- \[AGENT-SKILLS\] [Agent Skills specification](https://agentskills.io/specification), as published.
- \[AGENT-SKILLS-DISCOVERY\] [Agent Skills discovery via well-known URIs](https://github.com/cloudflare/agent-skills-discovery-rfc), version 0.2.0.
- \[AI-CATALOG\] [AI Catalog](https://ai-catalog.io/spec), draft, `specVersion` 1.0.
- \[APPNOTE\] [PKWARE APPNOTE](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT), the ZIP format.
- \[CLAUDE-CODE-MARKETPLACE\] [Claude Code plugin marketplace reference](https://code.claude.com/docs/en/plugins/marketplace-reference), Claude Code 2.1.224 or later.
- \[FIPS180-4\] NIST, [Secure Hash Standard (SHS)](https://doi.org/10.6028/NIST.FIPS.180-4), FIPS PUB 180-4, August 2015.
- \[HTML\] WHATWG, [HTML Living Standard](https://html.spec.whatwg.org/multipage/).
- \[JSON-LD\] W3C, [JSON-LD 1.1](https://www.w3.org/TR/json-ld11/), Recommendation, July 2020.
- \[JSON-SCHEMA\] [JSON Schema 2020-12](https://json-schema.org/draft/2020-12), core and validation vocabularies.
- \[LLMS-TXT\] [llms.txt](https://llmstxt.org/), proposal.
- \[RFC2119\] S. Bradner, [Key words for use in RFCs to Indicate Requirement Levels](https://www.rfc-editor.org/rfc/rfc2119), BCP 14, RFC 2119, March 1997.
- \[RFC3629\] F. Yergeau, [UTF-8, a transformation format of ISO 10646](https://www.rfc-editor.org/rfc/rfc3629), STD 63, RFC 3629, November 2003.
- \[RFC3986\] T. Berners-Lee, R. Fielding and L. Masinter, [Uniform Resource Identifier (URI): Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986), STD 66, RFC 3986, January 2005.
- \[RFC8174\] B. Leiba, [Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words](https://www.rfc-editor.org/rfc/rfc8174), BCP 14, RFC 8174, May 2017.
- \[RFC8259\] T. Bray, [The JavaScript Object Notation (JSON) Data Interchange Format](https://www.rfc-editor.org/rfc/rfc8259), STD 90, RFC 8259, December 2017.
- \[RFC8615\] M. Nottingham, [Well-Known Uniform Resource Identifiers (URIs)](https://www.rfc-editor.org/rfc/rfc8615), RFC 8615, May 2019.
- \[SCHEMA-ORG\] [schema.org `SoftwareApplication`](https://schema.org/SoftwareApplication).
- \[SEMVER\] [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
- \[SPDX\] [SPDX license expressions](https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/), SPDX Specification 3.0.1, Annex B.
Informative:
- \[AGENT-PLUGINS\] [Agent Plugins 1.0](https://agent-plugins.org/).
- \[ANTIGRAVITY\] [Antigravity plugins](https://antigravity.google/docs/plugins).
- \[CODEX\] [Codex plugins](https://developers.openai.com/codex/plugins/build).
- \[GEMINI-CLI\] [Gemini CLI extensions](https://geminicli.com/docs/extensions/reference/).
- \[GH-PAGES\] [GitHub Pages limits](https://docs.github.com/en/pages/getting-started-with-github-pages/github-pages-limits).
- \[GNU-SHA256SUM\] [GNU `sha256sum`](https://www.gnu.org/software/coreutils/manual/html_node/sha2-utilities.html), GNU Coreutils manual.
- \[GROK-BUILD\] [Grok Build plugins](https://docs.x.ai/build/features/skills-plugins-marketplaces).
- \[REFERENCE-IMPLEMENTATION\] [jekyll-theme-modootoday](https://github.com/modootoday/jekyll-theme-modootoday), the reference implementation.
- \[REPRO-ARCHIVES\] [Reproducible builds: archives](https://reproducible-builds.org/docs/archives/).
- \[RFC3552\] E. Rescorla and B. Korver, [Guidelines for Writing RFC Text on Security Considerations](https://www.rfc-editor.org/rfc/rfc3552), BCP 72, RFC 3552, July 2003.
- \[RFC6973\] A. Cooper et al., [Privacy Considerations for Internet Protocols](https://www.rfc-editor.org/rfc/rfc6973), RFC 6973, July 2013.
- \[RFC8126\] M. Cotton, B. Leiba and T. Narten, [Guidelines for Writing an IANA Considerations Section in RFCs](https://www.rfc-editor.org/rfc/rfc8126), BCP 26, RFC 8126, June 2017.
## Annex D. Changes
- 0.1.0-draft: first editor's draft.
` a skill name and `/SKILL.md` for one or more skills, in the Agent Skills layout. Each skill becomes one plugin with the same name and the single skill ``.
- The plugin version is the `version` parameter (section 4.3). A generator MAY read it from a package manifest instead, but the value MUST be the same for every skill of the input.
- The plugin description is the skill's `description`.
- The plugin license is the skill's `license` front matter field, or else the `license` parameter.
- The generator synthesizes a plugin manifest `.claude-plugin/plugin.json` whose content is the canonical JSON (section 7.1) of an object with exactly the members `description`, `license`, `name` and `version`.
- The plugin directory is the synthesized manifest plus every file of `skills//` at `skills//` inside the plugin.
Input A has no agents, commands, hooks or MCP servers. A publisher who needs them uses input B.
### 4.2. Input B: a Claude Code marketplace
The input root holds `.claude-plugin/marketplace.json` in the Claude Code format, with plugins in subdirectories.
- The marketplace `name`, `owner` and `metadata.description` become the catalog's `marketplace.name`, `marketplace.owner` and `marketplace.description`.
- An entry whose `source` is a relative path (`./...`) is a local plugin. The generator reads and packages it.
- An entry whose `source` is an object of type `github`, `url`, `git-subdir` or `npm` is an external plugin. The generator lists it under `external` in the catalog (section 7.7) and MUST NOT fetch or package it.
- Entries of any other source type MUST be rejected (`source-type`).
- For a local plugin, `version` is taken from `.claude-plugin/plugin.json`, else from the entry. If both are present and differ, the input MUST be rejected (`version-mismatch`). If neither is present, the input MUST be rejected (`version-missing`).
- The display fields `description`, `license`, `displayName`, `author`, `homepage`, `repository` and `keywords` are taken from the entry when present, else from `plugin.json`. `category` and `tags` are taken from the entry.
- Entry component fields (`commands`, `agents`, `skills`, `hooks`, `outputStyles`, `themes`) and `strict` are copied unchanged into the URL-mode marketplace entry (section 8.3). They do not change the plugin directory.
Components of a local plugin are found by the standard layout, relative to the plugin directory:
| Component | Found at | Recorded as |
|---|---|---|
| skills | `skills//SKILL.md` | skill names, sorted |
| agents | `agents/*.md` | paths, sorted |
| commands | `commands/**/*.md` | paths, sorted |
| hooks | `hooks/hooks.json` | one item per handler (section 7.3) |
| MCP servers | `.mcp.json` | one item per server, sorted by name |
### 4.3. Generator parameters
| Parameter | Required | Meaning |
|---|---|---|
| `source` | yes | `skills` (input A) or `marketplace` (input B) |
| `siteUrl` | yes | The site origin: `https://` plus host and optional port, no path, no trailing slash |
| `base` | yes | The base namespace path, starting and ending with `/`. Default `/.agent-marketplace/` |
| `pages` | yes | The path of human-readable pages, starting and ending with `/`. Default `/plugins/` |
| `marketplace` | input A | Object with `name`, `owner` (`{"name": ...}`) and optional `description` |
| `version` | input A | The version of every plugin (section 4.1) |
| `license` | no | Input A license when a skill has none |
| `lock` | no | The path of the lock (section 11.2) relative to the input root, when the generator is told where it is |
| `hostPackages` | yes | Annex A packages to produce: any of `codex`, `antigravity`, `gemini`, `bundle`. Can be empty |
How an implementation receives these parameters (a configuration file, command-line flags) is out of scope. The conformance suite passes them in `case.json` (section 16.2).
The entry points of section 5 are defined at the origin root. A site whose content is served under a path prefix, such as a GitHub project site at `https://owner.github.io/repo/`, cannot publish them and does not conform. Generators SHOULD warn about this and SHOULD recommend a custom domain.
### 4.4. Input validation
A generator MUST check the input before writing any file, and MUST NOT publish anything when a check fails. Each check has a rule identifier. A generator SHOULD report the identifiers of every failed check; the conformance suite compares them (section 16.2).
| Rule | Requirement |
|---|---|
| `name-format` | Every plugin, skill and marketplace name matches `^[a-z0-9]+(-[a-z0-9]+)*$` and is at most 64 characters. This is the intersection of what the supported hosts accept. |
| `name-directory` | A skill's `name` equals its directory name. A local plugin's entry `name` equals the `name` in its `plugin.json` when that file exists. |
| `name-duplicate` | No two plugins share a name, and no two skills share a name across the whole input. |
| `name-reserved` | The marketplace name, and the URL-mode name derived from it (section 8.3), is not reserved by Claude Code (for example, names starting with `claudeai`). |
| `description-length` | Every plugin and skill description is 1 to 1,024 characters. |
| `license-missing` | Every plugin has a license, as an [SPDX license expression](https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/). |
| `version-format` | Every version is a [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) version without build metadata, at most 64 characters. |
| `version-missing` | Every local plugin has a version (section 4.2). |
| `version-mismatch` | Entry and `plugin.json` versions agree (section 4.2). |
| `source-type` | Every input B entry has a supported source type (section 4.2). |
| `path-escape` | Every component path and every relative source stays inside its plugin directory and contains no `..` segment. |
| `symlink` | The input contains no symbolic links inside a plugin or skill directory. |
| `reference-closure` | Every relative link or image target in a Markdown file resolves to an existing file inside the same skill directory, for files in a skill, or inside the same plugin directory, for other files (section 13.2). |
| `portable-path` | Every file path inside a plugin meets section 10.3. |
| `case-collision` | No two paths in one plugin differ only in letter case. |
| `file-size` | No file exceeds 25 MiB, and no archive exceeds 100 MiB. |
| `lock-violation` | No published version changes content (section 11.2). |
| `frontmatter` | Every `SKILL.md` starts with YAML front matter holding `name` and `description`. |
`SKILL.md` files longer than 500 lines SHOULD produce a warning, not a failure.
## 5. Entry points
### 5.1. Fixed paths
A conforming site publishes these files at these paths, relative to the origin. They are the only files a client is expected to find without a link.
| Path | Defined by | Content | Required |
|---|---|---|---|
| `/.well-known/ai-catalog.json` | AI Catalog | section 8.1 | yes |
| `/.well-known/agent-skills/index.json` | Agent Skills discovery 0.2.0 | section 8.2 | when the catalog has at least one skill |
| `/.claude-plugin/marketplace.json` | Claude Code convention | section 8.3 | yes |
| `/llms.txt` | llms.txt | section 5.2 | yes |
Under `/.well-known/agent-skills/`, the generator MUST write only the index and the skill archives of section 10.1, at `/.well-known/agent-skills//.zip`. Any other file there could collide with a skill name.
A generator MUST NOT create any other name under `/.well-known/`. RFC 8615 requires new well-known names to be registered, and this profile registers none (section 15).
### 5.2. The llms.txt section
The generator adds one section to `/llms.txt`. If the site already has an `/llms.txt`, the section is appended to it and the rest of the file is kept unchanged. If the site has none, the generator writes `# ` and the marketplace name as the first line, a blank line, and then the section.
The section is the following lines, each ended by a line feed (LF), with values substituted. The `agentSkillsIndex` line is present only when that entry point exists. One plugin line follows per plugin, sorted by name.
```text
## Agent marketplace
- [AI catalog](.json` | one skill entry | 7.6 |
| `/.claude-ai.zip` | Claude app upload archive | 10.1 |
| `/` |
| `entryUrl` | the URL of the skill's entry document |
### 7.5. Host support levels
`hosts` gives each host one of `native` (every component works), `partial` (some components do not work on that host) or `none` (no component works). A component is unsupported on a host when it appears in that host's row below. The level is `native` if the plugin has no unsupported component, `none` if it has components and all of them are unsupported, and `partial` otherwise.
| Host | Unsupported components |
|---|---|
| Claude Code | none |
| Grok Build | none (it reads Claude Code plugins) |
| Codex | agents, commands, hooks |
| Antigravity | commands, hooks |
| Gemini CLI | agents; hooks whose event is not one of `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Stop`, `PreCompact`, `Notification` |
These rows summarize the host formats as of this draft and change with them; Annex A gives the detail.
### 7.6. Entry documents
For every plugin item, the generator writes `.json`. An entry document is the item with three members added: `$schema` (`https://static-agent-marketplace.org/schemas/draft/entry.schema.json`), `kind` (`plugin` or `skill`) and `specVersion`. Nothing else is added or removed. Its schema is [`entry.schema.json`](../../schemas/draft/entry.schema.json).
An entry document is the machine-readable form of the page that describes the same package, and the page links it (section 9).
### 7.7. External entries
An external entry has `name`, `source` copied from the input, and `description` and `version` when the input has them. The generator lists it so that the catalog is complete, but it produces no archive, file list, entry document or install prompt for it, and does not list it in the upstream documents of section 8.
## 8. Upstream documents
### 8.1. AI Catalog
`/.well-known/ai-catalog.json` is an AI Catalog document with `specVersion` `1.0`, a `host` with `displayName` set to the owner name, and these entries:
| Entry | `identifier` | `type` | `url` | Other members |
|---|---|---|---|---|
| each skill | `urn:air:` | `application/agent-skills+zip` | the skill archive | `description`, `digest`, `version` |
| each plugin | `urn:air: skill entry`:
```html
```
These links use `rel="alternate"`, the relation llms.txt uses for a page's Markdown version (`type="text/markdown"`). They sit next to that link as siblings that differ only in `type` and `title`. Attribute values are HTML-escaped. Every page is a valid place to start discovery, which matters because a static host such as GitHub Pages cannot add HTTP `Link` headers.
AI Catalog also defines a `rel="ai-catalog"` link relation. A page MAY carry it in addition.
A page about a package SHOULD also describe it with a [schema.org `SoftwareApplication`](https://schema.org/SoftwareApplication) object in [JSON-LD](https://www.w3.org/TR/json-ld11/) whose `softwareVersion` and `downloadUrl` match the entry. `rel="alternate"` is not used for archives, which are not another representation of the page.
## 10. Archives and digests
### 10.1. Three archive shapes
Hosts expect different layouts, so each package is published in the shape its reader expects.
| Archive | Path | Top level of the archive | Read by |
|---|---|---|---|
| Plugin archive | `/.zip` | the skill root (`SKILL.md`, ...) | Agent Skills discovery clients |
| Claude app upload | `/.claude-ai.zip` | one folder `/` holding the skill | manual upload to the Claude apps |
The members of a plugin archive are the files of the plugin directory (section 4). The members of a skill archive are the files of `skills//` with that prefix removed. The members of a Claude app upload archive are the skill archive members with the prefix `/` added.
### 10.2. Canonical encoding
Every archive MUST be encoded exactly as follows, so that any two implementations produce the same bytes from the same members.
1. ZIP format as described by the [PKWARE APPNOTE](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT), without ZIP64, encryption, data descriptors, extra fields, comments or directory entries.
2. Members ordered by path, comparing UTF-8 bytes.
3. Every member stored without compression (method 0).
4. Every local header: version needed 20, flags 0, method 0, modification time 0x0000 and date 0x0021 (1980-01-01 00:00:00), CRC-32, compressed and uncompressed size equal, name length, extra length 0.
5. Every central directory header: version made by 0x0314 (Unix, 2.0), version needed 20, flags 0, method 0, the same time, date, CRC-32 and sizes, extra, comment and disk number 0, internal attributes 0, external attributes equal to the Unix mode `0100644` or `0100755` shifted left by 16 bits, and the offset of the local header.
6. One end of central directory record with disk numbers 0, both entry counts equal, the central directory size and offset, and no comment.
Stored entries cost size but remove every dependence on a compression library, which would otherwise make archives differ between implementations (see [Reproducible builds: archives](https://reproducible-builds.org/docs/archives/)). Text-heavy plugins are usually small; section 4.4 caps archives at 100 MiB.
### 10.3. Members, paths and modes
- Paths use `/` and are relative to the archive root. Each segment matches `^[A-Za-z0-9._-]+$` and is not `.` or `..`; the whole path is at most 240 characters. Segments MUST NOT be Windows device names (`CON`, `PRN`, `AUX`, `NUL`, `COM1` to `COM9`, `LPT1` to `LPT9`, with or without an extension).
- Only regular files are members. Empty directories are not represented.
- The mode is `0755` when the input file is executable (git mode `100755`) and `0644` otherwise.
- Member bytes are the input bytes unchanged, with the single exception of the manifest synthesized for input A.
### 10.4. SHA256SUMS
`" skill, version ".
3. Before using it, show me the files in its scripts folder and wait for my approval.
The skill archive sha256 is .html`). For reject cases, only `rejection.json` with the expected rule identifiers.
- `SHA256SUMS`: the digest of every file under `expected/`.
An implementation passes an accept case when it writes exactly the files under `expected/`, outside `_fragments/`, with identical bytes, and produces the fragments when asked. It passes a reject case when it writes nothing and reports at least the listed rules. A conformance claim names the suite version and passes every `required` case.
The suite tests generators only. A case whose `parameters` name a `lock` holds that lock in `input/`; a case without it has no lock, whatever file name an implementation uses by default (section 11.2).
### 16.3. Schemas and prose
The JSON Schemas of a version describe the structure of the documents that version defines. Where a schema and the prose differ, the prose governs. A schema is never stricter than the prose: a document that meets the prose validates against its schema, and a schema that rejects such a document is a defect in the schema. A schema can be looser, because some rules, such as sort order, digests and canonical form, are not expressed in JSON Schema.
## 17. Implementation notes (informative)
- Both build paths give the same site. On GitHub Pages a site can be built by the classic branch build (the `github-pages` gem, Jekyll 3.10, safe mode) or by a GitHub Actions workflow. A generator that runs before Jekyll, and writes its output into the site source, works with both: the classic path commits the output, the Actions path writes it just before the build. An implementation is expected to give byte-identical sites through both paths, and to check this in its own CI. This is a condition on implementations, not on the format.
- Jekyll skips paths that start with a dot. Sites need `include: [.well-known, .claude-plugin, .agent-marketplace]` (and `.agents`, `.antigravity-plugin` for Annex A trees). Actions deployments with `actions/upload-pages-artifact` also need `include-hidden-files: true`, or the dot directories are dropped silently. Do not add `.nojekyll`, which turns off the classic build.
- Files with YAML front matter, such as `SKILL.md`, are rendered by Jekyll. A generator has to make sure the published bytes are the input bytes, for example by serving them from a path Jekyll copies unchanged, and is advised to check the built site.
- GitHub Pages limits a site to 1 GB and a deployment to 10 minutes. A generator can warn well before the size limit and keep the number of retained versions small.
- The reference implementation is [jekyll-theme-modootoday](https://github.com/modootoday/jekyll-theme-modootoday).
## Annex A. Per-host packaging (informative)
This annex describes the optional *host packages* for hosts that cannot install from a URL. Host formats change often; the host documentation is authoritative: [Agent Plugins 1.0](https://agent-plugins.org/), [Codex plugins](https://developers.openai.com/codex/plugins/build), [Antigravity plugins](https://antigravity.google/docs/plugins), [Gemini CLI extensions](https://geminicli.com/docs/extensions/reference/) and [Grok Build plugins](https://docs.x.ai/build/features/skills-plugins-marketplaces).
### A.1. Host tree
With any `hostPackages`, the generator writes `