idx-md

# idx.md ## Purpose - Markdown registry for AI agent libraries and resources. - Agents can browse to learn everything they could use, then fetch the exact markdown. ## Index locations - All topics (full listing, alphabetical): https://idx.md/data/index.md (canonical) or https://idx.md/index.md (alias) - Capability navigation (browse by what the agent can do): https://idx.md/category/index.md - Scenario navigation (browse by workflow / use-case): https://idx.md/scenario/index.md - Industry navigation (browse by domain / vertical): https://idx.md/industry/index.md ## How to choose a navigation mode - If you know what you want: start from `/data/index.md` and search by keywords in titles/tags. - If you want tools by capability: start from `/category/index.md`. - If you have a specific workflow/use-case: start from `/scenario/index.md`. - If you're operating in a specific domain: start from `/industry/index.md`. ## Index entry format - Each entry is a HEAD frontmatter block followed by a topic line. - Topic line format: `|/data/{topic}|` - The index may start with a short HTML comment preamble; entries begin at the first `---` frontmatter block. --- ...frontmatter... --- |/data/openclaw| ## How to fetch - Read `https://idx.md/data/index.md` (or `https://idx.md/index.md`). - Choose `{topic}` from the `|/data/{topic}|` line. - HEAD metadata: `https://idx.md/{topic}` (or `/data/{topic}/HEAD.md`) - Vector shard (for embedding recall): `https://idx.md/{topic}/vectors.json` - BODY content: `https://idx.md/{topic}/BODY.md` - After download, compute SHA-256 on the raw BODY bytes and compare to `content_sha256` in HEAD frontmatter. - Use `retrieved_at` to decide whether a cached BODY needs refresh. ## Vector-based retrieval (recommended) - Use `/{topic}/vectors.json` as the retrieval layer, then fetch `/{topic}/BODY.md` only for top candidates. - Each `vectors.json` currently contains one `head` record derived from HEAD metadata. - Build/query embeddings on `records[].text`. - Use `records[].metadata.content_sha256` as your embedding cache key; only re-embed when it changes. - Suggested flow: 1. Collect topic candidates from `/data/index.md` or category/scenario/industry indexes. 2. Fetch each candidate's `/{topic}/vectors.json`. 3. Rank by vector similarity (optionally hybrid with lexical/tag score). 4. Fetch `/{topic}/BODY.md` for top-k and generate final answer from BODY. ## URL map - `/`, `/skill.md`, `/SKILL.md` -> this document - `/index.md`, `/data/index.md` -> index listing - `/category/index.md` -> category index listing - `/category/{category}/index.md` -> category topic listing - `/scenario/index.md` -> scenario index listing - `/scenario/{scenario}/index.md` -> scenario topic listing - `/industry/index.md` -> industry index listing - `/industry/{industry}/index.md` -> industry topic listing - `/{topic}` -> `/data/{topic}/HEAD.md` - `/{topic}/HEAD.md` -> HEAD metadata - `/{topic}/vectors.json` -> vector shard for embedding recall - `/{topic}/BODY.md` -> BODY content ## Constraints - `.md` only; `.mdx` rejected by filename. ## Integrity / Hash - `content_sha256` lives in the HEAD frontmatter. - `content_sha256` is the SHA-256 of the exact BODY bytes (no normalization). - Format: lowercase hex string. - Verify by hashing the downloaded BODY.md bytes and comparing to `content_sha256`. - If the hash differs, re-download BODY.md. ## Example flow - Read `/index.md` -> pick `openclaw` -> fetch `/openclaw/HEAD.md` -> fetch `/openclaw/BODY.md`. ## Contribute If you find a high-quality markdown resource that agents should know about, please open a PR to add it. Repo: https://github.com/Keith-CY/idx.md ### What to add - Add new sources to `sources/general.yml`. - Use a direct markdown URL (`.md`) and prefer `raw.githubusercontent.com` for GitHub content. - `.mdx` files are rejected. - Choose a `type` and `slug` that match `^[a-z0-9][a-z0-9-]*$`. - Avoid editing auto-generated registries (`sources/openclaw.yml`, `sources/openai.yml`, etc.) or `data/` outputs directly. ### Minimal entry example ```yaml - type: skills slug: acme-awesome-skill source_url: https://raw.githubusercontent.com/acme/awesome-skill/main/SKILL.md title: Awesome Skill (optional) summary: One-line summary (optional) tags: - skills license: MIT (optional) upstream_ref: https://github.com/acme/awesome-skill/blob/main/SKILL.md (optional) ``` ### How to submit 1. Fork the repo: https://github.com/Keith-CY/idx.md 2. Add your entry to `sources/general.yml`. 3. Open a PR with a short note on why the source is valuable for agents. 4. If you can run the build, include generated `data/` updates; otherwise the maintainer will handle it. Thanks for helping keep idx.md useful and current.