{
  "markdown": "<!-- SPDX-FileCopyrightText: 2026 Sebastien Rousseau -->\n<!-- SPDX-License-Identifier: MIT -->\n\n# AgtMLS — Agent Multiple Listing Service\n\n**The universal agent skills registry.**\n\n`agtmls` is the central nervous system for LLM prompts, skills, and\nsystem instructions across a polyglot ecosystem (Python, Rust, C++,\nGo, JS). By acting as a single source of truth, it ensures that\nwhether you use Claude Code, Aider, GitHub Copilot CLI, or Codex,\nthe AI behaves consistently, adheres to strict security standards,\nand writes idiomatic code for the target language.\n\n## Directory structure\n\n```\nagtmls/\n├── scripts/\n│   ├── setup-workspace.sh       # Links AgtMLS into your active repos\n│   ├── agtmls-doctor.py         # Local health checks for the registry\n│   └── generate-skill-index.py  # Builds index.json for discovery\n├── system-prompts/              # Global behavioural rules → repo-root CLAUDE.md/AGENTS.md/CONVENTIONS.md\n│   ├── _base.md                 # Universal engineering standards\n│   └── <lang>.md                # Per-language idiom profiles: rust, python,\n│                                # go, cpp, swift, typescript, javascript,\n│                                # ruby, bash (all authored)\n├── skills/                      # FLAT: every skill is skills/<name>/SKILL.md\n│   ├── writing-plans/           # Discipline skills: plan → test → debug →\n│   ├── test-driven-development/ #   verify → review → hand off. Apply in\n│   ├── systematic-debugging/    #   any repo, any language\n│   ├── verification-before-completion/\n│   ├── receiving-code-review/\n│   ├── handoff/\n│   ├── cross-language-port/     # Porting logic between polyglot repos\n│   └── noyalib-*/               # Project skills; bundle is a metadata field\n├── references/\n│   └── noyalib-bundle.md        # Routing index for the 14 noyalib skills\n├── commands/                    # Interactive slash commands (author here)\n├── evals/                       # Routing + behavioral skill checks\n├── lifecycle.json               # Skill proposal -> publication lifecycle\n├── profiles.json                # Named install/export profiles\n├── providers.json               # Native agent + plugin + export target matrix\n├── CHANGELOG.md                 # Human-readable changes\n├── RELEASE.md                   # Release checklist\n├── CATALOG.md                   # Generated human-readable registry catalog\n└── index.json                   # Generated skill registry metadata\n```\n\n## Install\n\nNo clone required:\n\n```bash\nuvx agtmls install rust claude --skills-only --bundle noyalib   # one-shot\npipx install agtmls && agtmls install rust claude               # persistent\n```\n\nThe package bundles the whole registry and is **dependency-free** — every\nscript is stdlib-only, so `uvx` is a single fast download with nothing to\nresolve. Browsing works the same way:\n\n```bash\nuvx agtmls list\nuvx agtmls search yaml\nuvx agtmls show cross-language-port\nuvx agtmls stats\n```\n\nInstalling from a package defaults to `--copy` rather than symlinks: the\nwheel lives in an ephemeral uvx/pipx cache, and linking into a cache that is\nabout to be collected would leave the target repo full of dangling links.\nPass `--copy` explicitly to get the same behaviour from a checkout.\n\nRepository-maintenance commands (`check`, `release-*`, `bump-version`,\n`diff`, `next-version`, `verify-release-assets`) need a real checkout and\nrefuse to run from a package. Point `AGTMLS_HOME` at a checkout to run the\ninstalled CLI against your own working tree:\n\n```bash\nAGTMLS_HOME=~/dev/agtmls agtmls check\n```\n\n## Install as a plugin\n\nAgtMLS reaches agents three ways, and `providers.json` records all three:\n\n| Section | Mechanism | Runtimes |\n|---|---|---|\n| `native_agents` | symlink install via `setup-workspace.sh` | Claude Code, Codex, Aider |\n| `plugin_targets` | the runtime's own plugin manifest | Antigravity, Codex, Cursor, Gemini CLI, Kimi, OpenCode |\n| `export_targets` | provider-adapted Markdown bundle | 13 targets, see below |\n\nPlugin installs need no clone:\n\n```\n# Claude Code\n/plugin marketplace add sebastienrousseau/agtmls\n/plugin install agtmls@agtmls\n\n# Antigravity\nagy plugin install https://github.com/sebastienrousseau/agtmls\n\n# Gemini CLI\ngemini extensions install https://github.com/sebastienrousseau/agtmls\n\n# Codex CLI      /plugins  -> search agtmls -> Install Plugin\n# Cursor         /add-plugin agtmls\n# Kimi Code      /plugins install https://github.com/sebastienrousseau/agtmls\n# OpenCode       see .opencode/INSTALL.md\n```\n\nEvery plugin manifest is **generated** from `.claude-plugin/plugin.json` and\nthe skill tree, so a version bump or a new bundle cannot leave one runtime\nbehind:\n\n```bash\npython3 scripts/agtmls.py plugin-manifests --write   # regenerate\npython3 scripts/agtmls.py plugin-manifests --check   # CI: fail on drift\n```\n\nThe manifests are `plugin.json` (Antigravity, at the repo root — it does not\nread `.claude-plugin/`), `.codex-plugin/plugin.json` plus\n`.agents/plugins/marketplace.json` (Codex), `.cursor-plugin/plugin.json`,\n`.kimi-plugin/plugin.json`, `gemini-extension.json` with `GEMINI.md`, and\n`.opencode/INSTALL.md`. OpenCode has no skill-bundle manifest, so it is\nwired through the `instructions` array in the user's `opencode.json`.\n\nUse the hub-and-spoke setup below instead when you want editable symlinks,\nper-language system prompts, or a native Aider install.\n\n## Hub-and-spoke setup\n\nDo NOT copy these files into your application repositories. Use the\nprovided script to symlink them so hub updates propagate instantly.\n\n1. Clone this hub: `~/dev/agtmls` (or wherever you keep it).\n2. Navigate to an application repo: `cd ~/dev/my-rust-microservice`.\n3. Link the rules:\n\n    ```bash\n    ~/dev/agtmls/scripts/setup-workspace.sh rust aider\n    ```\n\nThe script assembles the system prompt from `_base.md` + the language\nprofile and writes it to the **repo-root file the tool auto-loads**\n(`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex, `CONVENTIONS.md`\nfor Aider — the latter also registered in `.aider.conf.yml`). It then\nsymlinks every in-scope skill and command into the tool's dot-dir\n(`.claude/`, `.aider/`, `.codex/`, or `.agent/`), one level deep\n(`<cli>/skills/<skill>/`) where the tool can discover it. Re-run it any\ntime you add a language profile or a skill.\n\nThe assembled prompt is a per-machine artifact of the hub, not repo\ncontent — so the script adds it (and the tool's dot-dir) to the target\nrepo's local `.git/info/exclude`. It stays **private and un-committed**,\nsourced only from the hub, and re-running never dirties the working\ntree. (This is a personal, local ignore; it doesn't touch the committed\n`.gitignore`.)\n\n### Skills only (no system prompt)\n\nFor repos that consume AgtMLS *skills* but source their system prompt\nelsewhere (e.g. a global `~/.claude/CLAUDE.md`), pass `--skills-only`:\n\n```bash\n~/dev/agtmls/scripts/setup-workspace.sh rust claude --skills-only\n```\n\nIt links the skills without writing a prompt, and cleans up any prompt a\nprevious non-`--skills-only` run generated (a hand-authored prompt with\nno generated marker is left untouched). Use this flag on every run for\nthose repos so a future setup never re-creates the prompt.\n\n### The discipline skills\n\nSix skills cover ordinary engineering work in any repo and any language.\nThey are general (`\"bundle\": null`), so they install everywhere, and they\ncompose in phase order:\n\n| Phase | Skill | The rule it enforces |\n| --- | --- | --- |\n| Decompose | `writing-plans` | A step is done when something observable changes |\n| Build | `test-driven-development` | A test you have not seen fail proves nothing |\n| Diagnose | `systematic-debugging` | No edit before an explanation |\n| Finish | `verification-before-completion` | A claim you have not observed is a guess |\n| Review | `receiving-code-review` | Every comment gets a decision and a reply |\n| Pause | `handoff` | Can the reader act without asking you a question? |\n\nEach hands off to the next — debugging produces the explanation a red test is\nwritten from; that red-then-green is exactly the evidence the completion gate\ndemands. A project bundle's own rules override them on specifics.\n\nInstall just these with the `discipline` profile:\n\n```bash\nuvx agtmls install python claude --profile discipline\n```\n\n### General skills vs project bundles\n\nThe skill tree is **flat** — every skill is `skills/<name>/SKILL.md`, with no\nnesting. That is not cosmetic: each agent runtime scans its skills path\n*non-recursively*, so a nested skill is invisible to Codex, Cursor, Gemini\nCLI, Antigravity, and anything else that does not support an array-valued\n`skills` field.\n\nBundle membership is therefore the `bundle` field in each skill's\n`metadata.json`, not a parent directory:\n\n- **General skills** (`\"bundle\": null`) — `cross-language-port`,\n  `using-agtmls`. These apply anywhere and are **always linked**.\n- **Project skills** (`\"bundle\": \"noyalib\"`) — linked **only** when the\n  bundle is named with `--bundle`, so a project's skills never land in an\n  unrelated repo:\n\n```bash\n# a generic Python repo — general skills only, no project bundle\nsetup-workspace.sh python claude --skills-only\n\n# a noyalib-family repo — general skills + the noyalib bundle\nsetup-workspace.sh rust claude --skills-only --bundle noyalib\n```\n\nAll nine fleet languages have an authored profile — `rust`, `python`,\n`go`, `cpp`, `swift`, `typescript`, `javascript`, `ruby`, `bash`. A\nlanguage without a profile falls back to `_base.md` alone.\n\n## Adding a skill\n\nEvery skill lives in its own directory under `skills/` with at\nminimum a `SKILL.md` file. The frontmatter's `name` and\n`description` fields drive the router — write a description rich in\nverb-form triggers so a model can decide whether to load the skill\nfrom the description alone.\n\nFor a template, see `skills/cross-language-port/SKILL.md`, or scaffold one:\n\n```bash\npython3 scripts/agtmls.py scaffold-skill my-skill\n```\n\nProject-specific skills live beside every other skill and declare their\ngrouping with `\"bundle\": \"<name>\"` in `metadata.json`. Pass `--bundle` to\n`scaffold-skill` to set it.\n\n### The skill contract (CI-enforced)\n\n`scripts/validate-skills.py` runs on every push/PR\n(`.github/workflows/validate.yml`) and fails the build unless every\n`SKILL.md` satisfies:\n\n- a parseable YAML frontmatter block;\n- **only the six keys the [Agent Skills spec][spec] allows** — `name`,\n  `description`, `license`, `compatibility`, `metadata`, `allowed-tools`.\n  Any other key fails validation here and in `skills-ref validate`;\n- `name` present, ≤ 64 characters, kebab-case with no consecutive hyphens,\n  and equal to the skill's directory name;\n- `description` present, **≤ 1024 characters** (Claude Code truncates\n  beyond this), and containing a trigger cue (a \"when…\" / \"use for\" /\n  \"load before\" phrase telling the router when to load the skill);\n- `compatibility` ≤ 500 characters, and `metadata` a flat map of string\n  keys to string values, when either is present;\n- a top-level `# ` heading in the body;\n- **≤ 500 lines total**, so activation stays inside the\n  progressive-disclosure budget. Detail belongs in `reference.md`.\n\nRun it locally before pushing: `python3 scripts/validate-skills.py`.\n\n[spec]: https://agentskills.io/specification.md\n\n### Generated frontmatter\n\n`compatibility`, `metadata`, and `allowed-tools` are **generated** from each\nskill's `metadata.json` — do not hand-edit them:\n\n```bash\npython3 scripts/sync-skill-frontmatter.py --write   # regenerate\npython3 scripts/sync-skill-frontmatter.py --check   # CI: fail on drift\n```\n\n`metadata.json` stays the source of truth, but it is an AgtMLS-private\nsidecar that no other runtime reads. Mirroring it into the spec's fields is\nwhat gives a Cursor, Gemini CLI, or marketplace consumer the same risk\nsignal a native install gets. `required_tools` becomes `compatibility`;\n`safety_policy` becomes the namespaced `agtmls-*` keys under `metadata` and\nthe derived `allowed-tools` surface.\n\nNote that `allowed-tools` is experimental and runtimes disagree on its\nmeaning — some read it as a pre-approval, others as a restriction. AgtMLS\ndeclares the **full capability surface** the safety policy implies, which is\ncorrect under the restriction reading and pre-approves under the other.\nSwitch `ALLOWED_TOOLS_MODE` in `sync-skill-frontmatter.py` to `\"readonly\"`\nto declare only non-mutating tools instead.\n\n### Full local health check\n\nThe full list lives in [docs/checks.md](docs/checks.md). Run them all with:\n\n```bash\npython3 scripts/agtmls.py check\n```\n\nThe dispatcher wraps every registry operation; the full command reference is\nin [docs/cli.md](docs/cli.md).\n\n`index.json` is generated from the skill tree and committed so tools can\ndiscover skills without reading every body. Rebuild it after changing skills:\n\n```bash\npython3 scripts/generate-skill-index.py --write\npython3 scripts/generate-catalog.py --write\n```\n\nThe generated schema is documented in\n`references/registry-schema.md`; do not edit `index.json` by hand.\n\n### Repository location\n\nAgtMLS is intentionally a polyglot hub. It should not live under a\nPython-only folder unless your local machine has a personal convention for all\nautomation repos. The repo contains Python tooling, but its product surface is\nlanguage-neutral skills, prompts, commands, and evals.\n\n### Providers and profiles\n\nAgtMLS has native symlink installers for Claude Code, Codex, and Aider. Other\nAI providers are supported through provider-adapted Markdown exports generated\nfrom the same registry source of truth. Each export includes `ADAPTERS.md` plus\na provider-specific file such as `adapters/openai/AGENTS.md`,\n`adapters/anthropic/CLAUDE.md`,\n`adapters/github-copilot/.github/copilot-instructions.md`, or\n`adapters/cursor/.cursor/rules/agtmls.mdc`. `providers.json` records the native\nagent layouts and export targets; `profiles.json` records named subsets such as\n`minimal`, `polyglot`, `noyalib`, `security`, and `research`.\n\nUse exports when a provider does not have a first-class local skills directory:\n\n```bash\npython3 scripts/agtmls.py export --provider generic --profile polyglot --out-dir dist\npython3 scripts/agtmls.py export --provider anthropic --profile noyalib --out-dir dist\n```\n\nOptional live API smoke tests are available for configured model backends. They\nskip cleanly when credentials are absent and probe only metadata/list endpoints\nwhen present:\n\n```bash\npython3 scripts/smoke-live-providers.py\n```\n\nSupported credential variables are `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,\n`GEMINI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`, `QWEN_API_KEY`, and\n`OLLAMA_BASE_URL` for a reachable local Ollama server.\n\n### Safety metadata\n\nEvery metadata source must include `safety_policy` with explicit flags for\nnetwork access, file writes, command execution, secret handling, human-review\nrequirements, and risk level. The policy is validated by\n`validate-skill-metadata.py` and published into `index.json` so agents can\nroute or gate skills before use.\n\n### Import and release workflow\n\nExternal skills should enter as drafts, not directly as hardened skills:\n\n```bash\npython3 scripts/agtmls.py import-skill /path/to/external/skill --name external-skill\npython3 scripts/agtmls.py scaffold-skill follow-up-skill\npython3 scripts/agtmls.py release-check\n```\n\n`import-skill` normalizes a Markdown skill into `skills/imported/<name>/`, adds\ndraft metadata, creates a reference stub when needed, and review-gates the\nresult. Publish it only after adding routing and behavioral eval cases, filling\nout references, and passing `python3 scripts/agtmls.py check`.\n\n### Static docs site\n\n`site/index.html` is generated from the registry metadata and gives a browser-readable catalog with skill quality, risk, agent support, profiles, and export targets. Rebuild it after changing `index.json`, `profiles.json`, or `providers.json`:\n\n```bash\npython3 scripts/agtmls.py docs-site --write\n```\n\n### Release packs\n\n`release-pack` creates provider export archives plus `SHA256SUMS` and `release-manifest.json`:\n\n```bash\npython3 scripts/agtmls.py release-pack --profile polyglot --out-dir dist/release\n```\n\n### Evolution and evidence\n\n`evolve` creates a redacted local proposal from a transcript and requires human review before publication. `evidence` records per-skill invocation evidence with commands, touched files, outcome, and the skill safety policy. These files default to `.agtmls/` and are intentionally ignored.\n\n### Interoperability artifacts\n\n`agent-card.json` and `mcp-resources.json` are generated from the registry for A2A-style discovery and MCP-style resource publication. `SBOM.spdx.json` and `provenance.json` provide release supply-chain evidence.\n\n## Versioning\n\nAgtMLS follows the pre-1.0 patch-line policy in `VERSIONING.md`: public releases stay on `0.0.x` and increment by exactly `0.0.1`.\n\nPublished release assets can be verified after release with `python3 scripts/agtmls.py verify-release-assets --tag v0.0.1`.\n\nRelease tag protection is documented in `docs/tag-protection.md`.\n",
  "bytes": 17032,
  "sha": "09310ce3f21747069ff927ca32823a7643c4b86e08f85a07fad8fcf93e10b25b",
  "repo_slug": "sebastienrousseau/agtmls",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_sebastienrousseau_agtmls_e9a41b1e/readme"
}