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

- 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.