FIL-Builders · snissn · Mar 19, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -13,11 +13,33 @@ The current contribution model is the Markdown-native `v0.4` workflow. If you
 see older `0.1`-`0.3` files in the repo, treat them as historical context
 unless a current tutorial or prompt explicitly tells you to use them.
 
+## Canonical Packs Vs Generated Claude-Compatible Skills
+
+Agent Hub now has two artifact classes:
+
+- canonical packs in `agents/<tool>/<version>.md`
+- generated Claude-compatible skills in `distributions/claude/<tool>/<version>/`
+
+The canonical pack is the source of truth.
+The generated Claude-compatible skill is a derived distribution for
+Claude-compatible environments.
+
+Default contributor rule:
+
+1. edit the canonical pack
+2. regenerate the Claude-compatible skill
+3. do not hand-edit generated skill files unless the repo explicitly says otherwise
+
+If you need the distribution model explained in one place, read:
+
+- `tutorials/use-agent-hub-claude-compatible-skills.md`
+
 ## What A Good Contribution Looks Like
 
 The active Agent Hub surface is built around:
 
 - versioned Markdown packs in `agents/<tool>/`
+- generated Claude-compatible skills in `distributions/claude/`
 - intermediate documentation packs in `parse/`
 - generation prompts in `prompts/`
 - the normative spec in `spec/open-agent-spec-v0.4.0.md`
@@ -45,6 +67,9 @@ If you are generating or revising a pack with a local AI coding agent, also use:
 
 If a tool-specific generation brief already exists in `prompts/`, use that too.
 
+If your change should also refresh a generated Claude-compatible skill, plan to
+regenerate that distribution after updating the canonical pack.
+
 ## Contributing A New Or Updated Pack
 
 ### 1. Pick the target
@@ -55,6 +80,10 @@ Choose one of these paths:
 - improve an existing `0.4.0.md` pack
 - regenerate a pack using the current `v0.4` prompts and review process
 
+You may also need to regenerate:
+
+- `distributions/claude/<tool>/0.4.0/`
+
 If the repo already has an older pack for that tool, use it only as a coverage
 benchmark. Do not treat older generated packs as authoritative sources for API
 definitions.
@@ -81,7 +110,8 @@ The normal `v0.4` flow is:
 
 1. create or update the intermediate documentation pack in `parse/`
 2. create or update the final expert pack in `agents/<tool>/0.4.0.md`
-3. if needed, add or update a tool-specific generation brief in `prompts/`
+3. regenerate the Claude-compatible skill distribution when needed
+4. if needed, add or update a tool-specific generation brief in `prompts/`
 
 Use the checked-in prompts and runbook instead of inventing a new pack shape.
 
@@ -95,6 +125,21 @@ node scripts/validate-agent-pack-v0.4.0.js agents/<tool>/0.4.0.md
 
 Fix all structural failures before opening a PR.
 
+If the change affects a Claude-compatible distribution, regenerate and validate
+that output too:
+
+```bash
+npm run generate:claude-skill -- agents/<tool>/0.4.0.md
+npm run validate:claude-skill -- distributions/claude/<tool>/0.4.0
+```
+
+If you are touching one of the current pilot packs or modifying the compiler,
+also run:
+
+```bash
+npm run check:claude-skill
+```
+
 If you changed prompts or regenerated a pack that replaces an existing one,
 follow the evaluation process in:
 
@@ -122,6 +167,10 @@ npm run validate:agent-pack -- agents/<tool>/0.4.0.md
 
 The website and MCP surface only expose active packs from `agents/`.
 
+Generated Claude-compatible skills for active packs live in:
+
+- `distributions/claude/`
+
 Older packs that are no longer meant to appear in the live product are kept in:
 
 - `archive/agents/`
@@ -134,7 +183,7 @@ Use the archive only for historical preservation or recovery.
 Open a GitHub pull request with:
 
 - a short summary of what changed
-- the target pack or tutorial path
+- the target canonical pack, generated distribution, or tutorial path
 - validation results
 - evaluation results if you are replacing or regenerating an existing pack
 
@@ -147,6 +196,9 @@ We prefer contributions that stay reviewable:
 - clear source discipline
 - no speculative format changes without updating the spec or prompts that govern them
 
+If you regenerated a Claude-compatible skill bundle, say so explicitly in the PR
+body and include the command you used.
+
 ## UI, Docs, And Website Contributions
 
 Agent Hub is not only a pack registry. It also includes:
@@ -162,12 +214,21 @@ If you change public-facing site content or workflows:
 - preserve the existing visual language unless the change is intentionally a redesign
 - run `npm run build`
 
+If you change onboarding, MCP docs, or generated skill behavior, make sure the
+docs still distinguish clearly between:
+
+- canonical pack
+- generated Claude-compatible skill
+- MCP retrieval path
+- manual skill install path
+
 ## Need Help?
 
 If you are unsure how to contribute, start here:
 
 - `tutorials/authoritative-documents-for-v0.4-pack-generation.md`
 - `tutorials/evaluating-agenthub-pack-outputs.md`
+- `tutorials/use-agent-hub-claude-compatible-skills.md`
 - `agents/agent-hub/0.4.0.md`
 
 If something in the repo is ambiguous or stale, a pull request that fixes the

diff --git a/README.md b/README.md
@@ -1,60 +1,151 @@
-# AgentHub
+# Agent Hub
 
-> **The open registry & spec for API‑savvy LLM agents — built in public, one thoughtful file at a time.**
+> Expert guidance for AI coding agents, delivered as canonical Markdown packs and generated Claude-compatible skills.
 
----
+## What Agent Hub Is
 
-## What AgentHub *Is* (and Intentionally *Is Not*)
+Agent Hub now has two related artifact types:
 
-| **We Are** | **We Aren’t** |
-|------------|---------------|
-| **An open specification** (`Open Agent Spec v0.1`) that any LLM stack can read. | A proprietary prompt framework or closed vendor format. |
-| **A curated registry** of Markdown agent files with structured frontmatter—each a peer‑reviewed guide to using a specific API or SDK. | A one‑click black‑box CLI or SDK. Developers copy‑paste—or parse—the specs any way they like. |
-| **A conversation starter**: every agent PR includes design notes, context, and room for debate. | A “big bang” drop of autogenerated assets with no community input. |
+1. canonical versioned packs in `agents/<tool>/<version>.md`
+2. generated distributions built from those packs, including Claude-compatible skills in `distributions/claude/<tool>/<version>/`
 
----
+The canonical pack is the source of truth.
+Generated distributions are delivery formats built from that source.
 
-## Core Philosophy
+This gives Agent Hub two practical delivery paths:
 
-* **Quality > Quantity** — We’d rather publish ten rock‑solid agents than a hundred flimsy ones.  
-* **Transparency > Hype** — All design decisions, reviews, and mistakes happen in the open.  
-* **Collaboration > Control** — Maintainers guide the vision, but contributors co‑own the future.
+- runtime retrieval over MCP
+- file-based installation through generated Claude-compatible skills
 
----
+## Canonical Pack Vs Generated Claude-Compatible Skill
 
-## How to Get Involved
+### Canonical pack
 
-1. **Read the [CONTRIBUTING guide](./CONTRIBUTING.md)** — it walks you through our PR‑based workflow.  
-2. **Explore the founding agents** in [`/agents/`](./agents/) — they set the quality bar and include transparent `DESIGN_NOTES.md`.  
-3. **Pick an API or SDK** that’s missing and start drafting your own agent. Draft PRs welcome!  
-4. **Need help?** Open a Discussion or join our Discord office‑hours.
+The canonical pack is the authoritative authored artifact:
 
-*(First‑time contributors are always celebrated — add yourself to the all‑contributors grid!)*
+```text
+agents/<tool>/<version>.md
+```
 
----
+It is:
 
-## Tutorials
+- versioned
+- validated
+- reviewed directly in GitHub pull requests
+- the thing contributors should edit
 
-* [Getting Started: Loading Your First Agent File](./tutorials/getting-started-loading-your-first-agent-file.md)
-* [Authoritative Documents For v0.4 Pack Generation](./tutorials/authoritative-documents-for-v0.4-pack-generation.md)
-* [Evaluating AgentHub Pack Outputs](./tutorials/evaluating-agenthub-pack-outputs.md)
+### Claude-compatible skill
 
----
+The generated Claude-compatible skill is a delivery artifact:
 
-## Success Signals ✨
+```text
+distributions/claude/<tool>/<version>/
+  SKILL.md
+  references/
+  manifest.json
+```
 
-| Community Health Metric | Early‑Stage Target |
-|-------------------------|--------------------|
-| Community PRs merged (first 72 h post‑launch) | **≥ 3** |
-| PR review turnaround (launch week) | **≤ 12 h** |
-| Repeat contributors (first 2 weeks) | **≥ 5** |
-| Public projects tagged `#BuiltWithAgentHub` (first 14 days) | **≥ 5** |
-| Positive sentiment ratio in HN/PH comments | **> 70 %** |
+It is:
 
-We care less about vanity stars and more about **engaged, returning collaborators** who help the registry grow sustainably.
+- generated from the canonical pack
+- designed for progressive disclosure in Claude-compatible environments
+- a distribution target, not the primary authoring surface
 
----
+Default rule:
 
-*AgentHub operates under a [Code of Conduct](./CODE_OF_CONDUCT.md) to ensure a welcoming, harassment‑free environment for everyone.*
+- edit the canonical pack
+- regenerate the Claude-compatible skill
+- do not hand-edit generated skill files unless the repo explicitly says otherwise
 
-Happy agent‑crafting! 🌱
+## How To Use Agent Hub
+
+### Use MCP when you want runtime retrieval
+
+Use Agent Hub MCP when the agent should:
+
+- discover available packs
+- inspect versions
+- fetch the right pack only when a task needs it
+- keep prompts smaller and more repeatable
+
+Start here:
+
+- [Get Better Agent Answers with Agent Hub MCP](./tutorials/use-agent-hub-through-mcp.md)
+
+### Use the generated Claude-compatible skill when the environment wants a local skill
+
+Use the generated Claude-compatible skill when the environment expects:
+
+- a local `SKILL.md` bundle
+- file-based installation
+- progressive disclosure through a short skill entrypoint plus supporting files
+
+Start here:
+
+- [Use Agent Hub Claude-Compatible Skills](./tutorials/use-agent-hub-claude-compatible-skills.md)
+
+## Contributing
+
+Agent Hub is built in public through GitHub pull requests.
+
+Good starting points:
+
+- [CONTRIBUTING.md](./CONTRIBUTING.md)
+- [Authoritative Documents For v0.4 Pack Generation](./tutorials/authoritative-documents-for-v0.4-pack-generation.md)
+- [Evaluating AgentHub Pack Outputs](./tutorials/evaluating-agenthub-pack-outputs.md)
+
+If you are contributing packs, remember:
+
+- canonical pack first
+- generated distribution second
+- regenerate rather than hand-edit generated skill bundles
+
+## Local Commands
+
+Validate a canonical pack:
+
+```bash
+npm run validate:agent-pack -- agents/<tool>/0.4.0.md
+```
+
+Generate a Claude-compatible skill bundle:
+
+```bash
+npm run generate:claude-skill -- agents/<tool>/0.4.0.md
+```
+
+Generate the current pilot set:
+
+```bash
+npm run generate:claude-skill:pilot
+```
+
+Check generated Claude-compatible bundles for drift:
+
+```bash
+npm run check:claude-skill
+```
+
+Check the MCP distribution tools locally:
+
+```bash
+npm run check:mcp-distributions
+```
+
+Build the full site and synced static artifacts:
+
+```bash
+npm run build
+```
+
+## Repository Guide
+
+- `agents/` — canonical versioned packs
+- `distributions/claude/` — generated Claude-compatible skill bundles
+- `parse/` — intermediate documentation packs
+- `prompts/` — generation prompts and runbooks
+- `spec/` — normative format specs
+- `scripts/` — validators, generators, and sync tooling
+- `tutorials/` — user and contributor workflow guides
+- `website/` — Docusaurus site
+- `netlify/functions/mcp.js` — deployed MCP server