magi-markdown
llms.txt620 starsChanged 19 months agoApache-2.0View on GitHub
MDA is a Markdown superset for AI-agent artifacts. One .mda source can compile into the Markdown files that agent runtimes already load, including SKILL.md, AGENTS.md, MCP-SERVER.md, and CLAUDE.md, while preserving machine-readable metadata, dependencies, capabilities, relationships, integrity digests, and signatures. This file is the LLM-readable entry point for the mda-markdown repository. It follows the llms.txt style: short project context first, then a curated map of the most useful Markdown resources. Prefer these linked files over inferred memory when answering questions about…
We split this llms.txt into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Start from spec/v1.0/ for normative behavior, then use README and docs for explanation and examples.
- Very specific: line 13
Use @markdown-ai/cli for authoring, CI checks, deterministic compilation, canonicalization, and agent-side preflight checks.
- Distinctive: line 16
Keep generated MDA simple.
≈ “Common” is an estimate: at least 1 in 5 of the 3,225 llms.txt files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Keep what fits and drop the rest. Your version, ready for your agents.
Files
llms.txt
# MDA Open Spec > MDA is a Markdown superset for AI-agent artifacts. One `.mda` source can compile into the Markdown files that agent runtimes already load, including `SKILL.md`, `AGENTS.md`, `MCP-SERVER.md`, and `CLAUDE.md`, while preserving machine-readable metadata, dependencies, capabilities, relationships, integrity digests, and signatures. This file is the LLM-readable entry point for the `mda-markdown` repository. It follows the `llms.txt` style: short project context first, then a curated map of the most useful Markdown resources. Prefer these linked files over inferred memory when answering questions about MDA. MDA v1.0 defines the contract, schemas, conformance suite, and TypeScript reference CLI. Use it to author, validate, compile, integrity-check, and implement agent-facing Markdown artifacts in a way that is portable across supported target formats. High-priority rules for AI agents: - Start from `spec/v1.0/` for normative behavior, then use README and docs for explanation and examples. - Validate artifacts with `schemas/` and `conformance/manifest.yaml` before treating generated output as conforming. - Use `@markdown-ai/cli` for authoring, CI checks, deterministic compilation, canonicalization, and agent-side preflight checks. - For automation, use explicit targets and JSON output: `mda validate <file> --target source --json`, `mda compile <file> --target SKILL.md AGENTS.md --out-dir out --integrity`. - For runtime integration, implement a lightweight loader and verifier hook from the spec, schemas, and trusted runtime profile. - Keep generated MDA simple. Add MDA extensions when they encode metadata, dependencies, relationships, capabilities, integrity, or signatures that a human or agent can act on. Authoritative source order: 1. Normative spec files in `spec/v1.0/` 2. JSON Schemas in `schemas/` 3. Conformance manifest and fixtures in `conformance/` 4. CLI manual and implementation spec in `apps/cli/` 5. README, value docs, and architecture docs 6. Examples and translated documentation ## Start Here - [README.md](README.md): Main project overview, core value proposition, compatibility, CLI boundary, honest status, and links to spec sections. - [SPEC.md](SPEC.md): Short canonical index for the MDA Open Spec, including design priorities, authoring modes, governance, artifacts, and versioning. - [AI agent core value](docs/v1.0/ai-agent-core-value.md): Explains what MDA gives runtimes, harnesses, validators, dispatchers, and AI agents at load time. - [Human curator core value](docs/v1.0/human-curator-user-core-value.md): Explains why human maintainers and documentation curators use MDA instead of hand-maintaining multiple target files. - [v1.0 scope and roadmap](docs/v1.0/what-v1.0-does-not-ship.md): Release boundary notes for registry, verifier, resolver, graph indexer, harness routing, and future target coverage. ## Normative Spec - [Overview](spec/v1.0/00-overview.md): Terminology, conformance keywords, design priority order, authoring modes, wedge narrative, governance, versioning, and document map. - [Source and output](spec/v1.0/01-source-and-output.md): `.mda` source, compiled `.md` output, identity compile, compile direction, compiler responsibilities, and author responsibilities. - [Frontmatter](spec/v1.0/02-frontmatter.md): Extraction algorithm, open-standard fields, MDA extension fields, source vs output rules, timestamp portability, and version constraints. - [Relationships](spec/v1.0/03-relationships.md): Typed footnote relationships, `depends-on`, version-range grammar, digest pinning, and frontmatter mirrors. - [Platform namespaces](spec/v1.0/04-platform-namespaces.md): Vendor namespace rules, reserved keys, loader expectations, and registration rationale. - [Progressive disclosure](spec/v1.0/05-progressive-disclosure.md): Tiered artifact layout, `scripts/`, `references/`, `assets/`, file reference rules, and authoring discipline. - [Conformance](spec/v1.0/07-conformance.md): Validator and compiler conformance levels, suite execution, fixture index, and upstream compatibility expectations. - [Integrity](spec/v1.0/08-integrity.md): Integrity field shape, canonicalization, hashing, verification, multi-file artifacts, and examples. - [Signatures](spec/v1.0/09-signatures.md): DSSE PAE, Sigstore OIDC flow, `did:web` fallback, multiple signatures, and verification policy. - [Capabilities](spec/v1.0/10-capabilities.md): `metadata.mda.requires`, standard keys, consumer behavior, and examples for runtime/tool/network/package/model/cost hints. - [Implementer's guide](spec/v1.0/11-implementer-guide.md): Recommended loader algorithm, error categories, project-specific schemas, and reference implementation notes. - [Sigstore tooling integration](spec/v1.0/12-sigstore-tooling.md): Informative implementation guidance for Sigstore-related tooling and reference scripts. - [Trusted runtime profile](spec/v1.0/13-trusted-runtime.md): Production verification behavior, trust policy shape, error categories, and previous-good runtime behavior. ## Target Formats - [SKILL.md target schema](spec/v1.0/06-targets/skill-md.md): Target rules for agentskills.io-style skill packages, frontmatter fields, body, progressive disclosure, and validation. - [AGENTS.md target schema](spec/v1.0/06-targets/agents-md.md): Target rules for AAIF-aligned `AGENTS.md` files, allowed fields, body behavior, relationships, and validation. - [MCP-SERVER.md target schema](spec/v1.0/06-targets/mcp-server-md.md): Target rules for MCP server docs, sidecar requirements, cross-file consistency, and validation. - [CLAUDE.md target schema](spec/v1.0/06-targets/claude-md.md): Target planning notes for `CLAUDE.md` coverage. ## Schemas And Conformance - [Schemas directory](schemas/): JSON Schema 2020-12 definitions for source frontmatter, target frontmatter, footnote relationships, trust policy, integrity, signatures, dependencies, requirements, and version ranges. - [Source frontmatter schema](schemas/frontmatter-source.schema.json): Machine-checkable schema for source-mode `.mda` frontmatter. - [SKILL.md frontmatter schema](schemas/frontmatter-skill-md.schema.json): Machine-checkable schema for compiled `SKILL.md` frontmatter. - [AGENTS.md frontmatter schema](schemas/frontmatter-agents-md.schema.json): Machine-checkable schema for compiled `AGENTS.md` frontmatter. - [MCP-SERVER.md frontmatter schema](schemas/frontmatter-mcp-server-md.schema.json): Machine-checkable schema for compiled `MCP-SERVER.md` frontmatter. - [Relationship footnote schema](schemas/relationship-footnote.schema.json): Machine-checkable schema for typed JSON footnote payloads. - [Trust policy schema](schemas/mda-trust-policy.schema.json): Machine-checkable schema for trusted runtime policy files. - [Conformance README](conformance/README.md): Explains fixture layout, validator expectations, compiler expectations, and fixture contribution rules. - [Conformance manifest](conformance/manifest.yaml): Stable binding from fixture to rule id, expected verdict, and expected error category. - [Valid fixtures](conformance/valid/): Source artifacts that conforming validators must accept. - [Invalid fixtures](conformance/invalid/): Source artifacts that conforming validators must reject for the manifest-listed reason. ## CLI And Tooling - [CLI README](apps/cli/README.md): Minimal entry point for the `@markdown-ai/cli` npm package and installed `mda` binary. - [CLI manual](apps/cli/HOW-TO-USE.md): Practical quick start, AI-agent usage, human usage, command reference, global flags, exit codes, and current status. - [CLI implementation spec](apps/cli/IMPL-SPEC.md): Scope, CLI surface, module layout, conformance levels, release model, dependencies, compatibility tests, and out-of-scope items. - [CLI source](apps/cli/src/): TypeScript source for the reference CLI. - [CLI tests](apps/cli/test/): Tests for CLI behavior, compilation, validation, canonicalization, integrity, and conformance behavior. - [Create, sign, and verify guide](docs/create-sign-verify-mda.md): Manual path for writing MDA, adding integrity, signing, choosing trust policy, and verifying before loading. - [Developer guide](docs/developer-guide.md): Implementation-oriented guide covering validation pipeline, minimal validators, integrity, signature verification, conformance, and namespaces. ## Architecture And Registry - [Architecture](docs/architecture.md): Explains the three architectural components: YAML frontmatter, typed relationship footnotes, and optional cryptographic identity. - [Registry](REGISTRY.md): Namespace registry, standard `requires` keys, reserved Sigstore OIDC issuers, transparency log providers, and DSSE payload types. - [Contributing](CONTRIBUTING.md): Contribution workflow and expectations for changes. - [Security](SECURITY.md): Security policy and vulnerability reporting path. - [Changelog](CHANGELOG.md): Project change history. ## Examples - [Examples directory](examples/): Worked examples for MDA artifacts. - [MDA examples](docs/mda-examples/): Documentation examples that demonstrate MDA source patterns. - [Minimal example in README](README.md#minimal-example): Small source artifact showing baseline MDA frontmatter and body structure. ## Optional - [Documentation site config](docs/docs.json): Site-facing documentation config. - [Generated site MDX docs](docs/mdx/): Site-facing documentation material. - [Translated READMEs](docs/readme/): Localized README translations; use English canonical docs for normative interpretation. - [Images](images/): Diagrams used by README and documentation. ## Last Updated - 2026-05-09
Other versions1 project uses a version of this.
Word for word · 1
- sno-ai/mda★ 616100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- CLAUDE.mdCLAUDE.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.