[feature] Publish an official Moon Agent Skill for AI coding assistants

[Yuzu02]

Is your feature request related to a problem? Please describe

As AI-powered coding assistants (GitHub Copilot, Cursor, Claude Code, Codex CLI, Gemini CLI, etc.) become standard tools in developer workflows, their usefulness depends entirely on the quality of structured, machine-readable knowledge available about a given tool.

Moon is a powerful but nuanced build system — it has a specific CLI surface, a layered configuration model (.moon/workspace.*, .moon/toolchains.*, .moon/tasks/**/*, moon.*), support for multiple config formats (YAML, TOML, JSON, PKL), and a set of concepts (projects, tasks, tags, toolchains, layers, stacks, the task graph, WASM plugins, remote caching, affected detection, execution plans) that are non-trivial and not well-represented in LLM training data.

In practice, this means:

• LLMs hallucinate Moon CLI flags that don't exist, or confuse them with Nx/Turborepo equivalents.
• Assistants generate moon.* configs with invalid schema, wrong inheritance patterns, or missing required fields.
• v1 → v2 breaking changes (camelCase → kebab-case flags, toolchain.yml → toolchains.*, "touched files" → "changed files", moonbase sunset, WASM-based toolchains) are almost never reflected in LLM-generated output.
• Concepts like affected-files, task inheritance via .moon/tasks/**/*, tag-based inherited-by conditions, and the distinction between command+args vs script are consistently explained incorrectly.
• Developers waste time debugging AI-generated Moon configuration instead of building.

There is currently no official, canonical Agent Skill for LLMs to ground their understanding of Moon. While Moon already ships an llms.txt file on its website (added in v1.37.1), an MCP server via moon mcp, and a community skill exists (hyperb1iss/moonrepo-skill), none of these fully covers the gap: the llms.txt is a documentation index without procedural guidance, the MCP server provides dynamic tool access but not static knowledge grounding, and the community skill — while well-structured — is not versioned alongside Moon releases or maintained by the Moon team. An official Moon Skill — a structured, LLM-optimized knowledge document — would solve this gap directly, complementing the existing llms.txt and MCP server.

---

Describe the solution you'd like

An official Moon Skill published and maintained in the moonrepo/moon repository (or a dedicated moonrepo/moon-skills repo), structured for consumption by LLM coding assistants following the open Agent Skills specification published at agentskills.io. Additionally, improvements to the existing llms.txt on the Moon website to align with the llms.txt standard.

The Agent Skills standard uses a SKILL.md file with YAML frontmatter (name, description) that agents load with progressive disclosure: only the name and description are read at startup (zero context cost), and the full instructions are loaded only when the skill is triggered. This means a repository can have dozens of skills installed with no performance penalty. Skills are cross-platform by design — authored once, works everywhere the spec is implemented.

Proposed structure

Per the Agent Skills specification, each skill lives in a directory whose name must exactly match the name field in its SKILL.md frontmatter. The spec recommends keeping SKILL.md under 500 lines (< 5,000 tokens), with detailed reference material pushed to separate files that agents load only when needed (progressive disclosure). The spec does not mandate a single canonical skills directory — different agents scan different paths (.github/skills/, .claude/skills/, .agents/skills/, .opencode/skills/). The Skills CLI handles installation to each agent's expected path automatically.

skills/
├── moon/                        # directory name MUST match frontmatter `name: moon`
│   ├── SKILL.md                 # Required: YAML frontmatter + entry instructions (<500 lines)
│   ├── references/              # Loaded on-demand — zero context cost until accessed
│   │   ├── concepts.md          # workspace, project, task, toolchain, tag, layer, stack — precise definitions
│   │   ├── cli-reference.md     # moon run, moon exec, moon check, moon ci, moon query, moon sync, moon init, moonx, moon mcp
│   │   ├── config-reference.md  # Annotated schemas: workspace.*, toolchains.*, tasks/**/*.*, moon.*, extensions.*
│   │   ├── task-inheritance.md  # inherited-by (toolchains, stacks, layers), extends, merge strategies, command vs script
│   │   ├── affected-mode.md     # --affected, MOON_BASE/MOON_HEAD env vars, changed files, CI integration
│   │   ├── remote-caching.md    # Depot, self-hosted gRPC (Bazel RE API), cache keys, outputs correctness
│   │   ├── docker.md            # moon docker scaffold, moon docker setup, moon docker prune, Dockerfiles
│   │   ├── wasm-plugins.md      # Toolchain WASM plugins, extensions, PDK API
│   │   ├── execution-plans.md   # moon exec --plan, JSON plan format, CI job partitioning (v2.1+)
│   │   └── v2-migration.md      # Breaking changes from v1 → v2, moon migrate v2, kebab-case flags
│   └── assets/
│       ├── workspace-config.md  # Annotated real-world .moon/workspace.yml example
│       ├── project-config.md    # Annotated moon.yml with tasks, deps, docker, and tags
│       └── ci-pipeline.md       # Full GitHub Actions + moon ci / moon exec --plan integration example
└── proto/                       # Optional: companion skill for proto version manager
    ├── SKILL.md                 # proto install, proto use, .prototools, plugin system
    └── references/
        ├── commands.md
        └── config.md

What each section should cover

The spec recommends keeping SKILL.md under 500 lines and moving detailed material into references/ files that are linked from the body and loaded on demand. This drives the split below.

SKILL.md (entry point — should stay under 500 lines)

• YAML frontmatter with name: moon, description (1–1,024 chars, should include trigger keywords), optional license, optional compatibility, optional metadata (e.g., metadata.moon-version: "2.1" — custom extension)
• What Moon is and is not (vs. Nx, Turborepo, Bazel)
• Core concept glossary (workspace, project, task, toolchain, tag, layer, stack)
• Quick-reference table of the most common moon run / moon exec invocations
• Common mistakes / anti-patterns (critical for reducing hallucinations)
• v2-specific callouts: kebab-case flags, multi-format config, command+args vs script, WASM toolchains
• Links to each references/*.md file with a one-line description of when to load it
• Version of Moon this skill was written against

references/concepts.md

• Workspace, project, task, toolchain, tag, layer, stack — precise definitions with no ambiguity
• The task graph and how Moon evaluates execution order (DAG, topological order)
• Target syntax for CLI commands: project:task, :task, ~:task, #tag:task, glob patterns
• Configuration-only scopes (not valid as CLI targets): ^:task (upstream dependencies), ~:task (self-reference in deps/inputs)
• The .moon workspace root (and .config/moon alternative for reduced clutter)

references/cli-reference.md

• Every primary command (run, exec, check, ci, query, sync, init, mcp, docker, generate, ext, toolchain, setup, teardown, upgrade) with flags and common usage patterns
• Global options: --cache <MODE> (read-write/read/write/off), --log <LEVEL> (off/error/warn/info/debug/trace/verbose), --dump (trace profile), --theme (dark/light), --concurrency, --quiet
• Special emphasis on v2 changes: moon exec (low-level), moonx (shorthand binary), moon extension, interactive selection prompts when no identifier provided
• Clear distinction: moon run vs moon check vs moon ci vs moon exec
• moon mcp for AI agent integration via MCP server

references/config-reference.md

• Annotated schemas for .moon/workspace.*, .moon/toolchains.*, .moon/tasks/**/*, moon.*, .moon/extensions.*
• Required vs. optional fields, valid value types, defaults
• Multi-format support (YAML, TOML, JSON, PKL) — note the .* wildcard convention
• Cross-referenced with common mistakes in the SKILL.md entry point

references/task-inheritance.md

• How global tasks in .moon/tasks/**/* propagate to projects via inherited-by conditions
• inherited-by with toolchains, stacks, layers (supports or, not operators)
• extends, merge strategies (append, prepend, replace)
• command + args for simple commands; script for compound commands (pipes, redirects, chaining)
• Task presets (server, utility) and their defaults

references/affected-mode.md

• --affected, MOON_BASE/MOON_HEAD env vars, "changed files" (not "touched files" — renamed in v2)
• affected-files task option: boolean, "args", "env", or object form with filter (glob patterns), passDotWhenNoResults (v2.1), passInputsWhenNoMatch
• Full GitHub Actions integration example

references/remote-caching.md

• Depot (recommended hosted option) and self-hosted gRPC (Bazel RE API)
• ⚠️ moonbase has been sunset (v1.34.0) — do not reference as current
• Cache key anatomy, outputs correctness requirements

references/docker.md

• moon docker scaffold, moon docker setup, moon docker prune
• Docker config in moon.* (project-level): docker.file, docker.image, docker.build.setup, docker.build.prune, docker.build.run
• Tera template support for custom Dockerfiles

references/wasm-plugins.md

• How toolchains are now WASM plugins (not hard-coded)
• Extension plugins with define_extension_config, initialize_extension, extend_project_graph, etc.
• How to reference community toolchain plugins

references/execution-plans.md (v2.1+)

• JSON plan format for moon exec --plan
• Four top-level blocks: targets, pipeline, affected, graph
• CI job partitioning with --job and pipeline.jobTotal
• Dependency scope targeting: ^production:task, ^development:task (v2.1)

references/v2-migration.md

• All breaking changes: camelCase → kebab-case, toolchain.yml → toolchains.*, tasks.yml → tasks/**/*, "touched" → "changed"
• moon migrate v2 command
• command+args restrictions (simple commands only; use script for compound)
• Removed commands (moon node, moon migrate from-package-json, moon query hash, moon query hash-diff)
• Removed presets (watcher — removed in v2)
• .env file handling changes (deferred loading, *.local files)

---

Describe alternatives you've considered

1. Third-party community skills

The most notable existing effort is hyperb1iss/moonrepo-skill, a well-structured community skill covering both Moon and proto with references, examples, and slash commands. It demonstrates strong community demand for this capability. However, community skills are:

• Not versioned alongside Moon releases — they can drift as Moon evolves (e.g., the existing community skill references .moon/tasks/*.yml rather than the v2 .moon/tasks/**/* directory structure, and uses .yml extensions instead of the format-agnostic .* convention)
• Not authoritative — they reflect one maintainer's understanding, not the Moon team's
• Not automatically discoverable by developers using moon init

Other developers have created local skill files or Cursor rules for Moon. These share the same limitations.

2. Relying on the existing llms.txt, MCP server, and documentation site

Moon already ships an llms.txt on its website (added in v1.37.1), an MCP server via moon mcp (added in v1.37), and the documentation is comprehensive. However:

• The llms.txt is a documentation index — it does not contain the procedural, anti-pattern-aware, task-specific guidance that an Agent Skill provides
• The MCP server provides dynamic tool access (querying projects, running tasks) but not static knowledge grounding (correct config patterns, common mistakes, migration guidance)
• The documentation site is not structured for LLM consumption (no explicit "common mistakes" section, no machine-readable schema summaries)
• LLMs cannot reliably fetch and parse HTML documentation at inference time in most environments
• Neither format maps to the progressive disclosure model that Agent Skills use (metadata → instructions → references)

An official Skill is complementary to all three — the Skill handles procedural "how to use Moon correctly" knowledge; the llms.txt handles documentation discovery; the MCP server handles runtime interaction.

3. Auto-generated API reference

Moon generates JSON Schemas to .moon/cache/schemas for all config files (via moon sync config-schemas), and the VS Code extension auto-configures these. However, raw JSON Schema is poorly suited for LLM consumption — it lacks context, examples, and the explanatory prose that helps a model generate correct code. It also doesn't cover CLI usage, anti-patterns, or workflow guidance.

---

Additional context

Why this matters for adoption

Moon's learning curve is real. The configuration model is powerful but non-obvious, and the gap between "I know what Moon does" and "I can write correct Moon config from scratch" is wide. The v1 → v2 migration added another layer: developers and LLMs trained on v1 patterns will generate broken configs unless explicitly guided. LLM coding assistants are now the primary way many developers explore and adopt new tooling. If an LLM confidently generates broken Moon config (wrong file names, camelCase flags, moonbase references), that developer may abandon Moon before ever seeing its value.

A high-quality official Skill lowers that friction significantly.

Prior art in other projects

The industry has converged on two complementary standards for LLM-optimized documentation, and major tooling projects are already shipping both.

The llms.txt standard (the llms.txt proposal) — proposed by Answer.AI's Jeremy Howard in September 2024 — defines a curated, Markdown-formatted index at a project's root that tells AI agents which documentation to prioritize and where to find clean .md mirrors of each page. Notable adopters in the developer tooling space:

• Stripe (llms.txt) — ships multiple llms.txt files with an instructions section that steers AI agents toward current API primitives.
• Vercel (llms.txt) — publishes a llms-full.txt containing their platform docs in a single file for AI tools.
• Cloudflare (llms.txt) — ships one of the most extensive implementations with product-specific files and a llms-full.txt.
• Anthropic (llms.txt) — maintains a table of contents for their Claude API docs.

The Agent Skills standard (SKILL.md) — an open format maintained at Agent Skills, adopted across dozens of agent platforms including Claude Code, GitHub Copilot (VS Code + coding agent + CLI), Cursor, OpenAI Codex, Gemini CLI, Goose, Windsurf, Amp, OpenCode, Antigravity, Kilo Code, Kiro CLI, Roo Code, Trae, and more. Skills package procedural knowledge as a directory with a SKILL.md manifest that agents load progressively: metadata first, full instructions only when the skill is triggered. Key adopters include:

• Expo (expo/skills) — ships an official skill collection covering dev client setup, native UI patterns, SDK usage, and Tailwind/NativeWind configuration.
• Railway (railwayapp/railway-skills) — maintains a use-railway skill with route-first design, covering project setup, deployment, troubleshooting, and environment management via action-oriented references.
• Microsoft (microsoft/skills) — publishes 130+ skills across Azure, AI, and SDK domains with comprehensive test scenarios, MCP server configurations, and custom agents. Also maintains microsoft/azure-skills as a focused plugin with 20 curated Azure workflow skills.
• Vercel Labs (vercel-labs/agent-skills) — hosts React, Next.js, and web design skills.

The Skills Directory is the open community registry for this ecosystem — built and maintained by Vercel Labs (vercel-labs/skills). It hosts thousands of published skills, discoverable and installable with a single command:

npx skills add <owner/repo>

A Moon skill published under moonrepo/moon or moonrepo/moon-skills would be immediately discoverable by any developer running a skills-compatible agent. The existing community skill hyperb1iss/moonrepo-skill validates this demand and could serve as a starting point.

Moon would be well-positioned to lead in this space for the build tooling category.

Who would benefit

• Developers onboarding to Moon in an AI-assisted workflow (Cursor, Copilot, Claude Code, Codex CLI, Gemini CLI)
• Teams migrating from v1 to v2 who rely on AI for config refactoring
• Teams adopting Moon across a monorepo who use AI for config generation
• Contributors to Moon-adjacent tooling who need accurate conceptual references
• Anyone building Moon integrations who uses LLMs for boilerplate

Suggested ownership

A full implementation would cover two complementary surfaces:

1. Improve the existing moonrepo.dev/llms.txt — Audit the current file (added in v1.37.1) and expand it following the llms.txt specification with clean .md mirrors of key documentation pages, a curated table of contents, and an instructions section (like Stripe's approach) that steers AI agents toward v2 patterns and away from common v1 mistakes. This file should be updated automatically on each docs deployment.

2. An official Moon skill — Published under moonrepo/moon (or a dedicated moonrepo/moon-skills repo) following the Agent Skills specification. The structure is described above under "Proposed structure". Once published on the Skills registry, any developer can install it with a single command:

npx skills add moonrepo/moon

This makes the skill immediately available across all Agent Skills-compatible platforms with no per-platform configuration. The Skills CLI automatically installs to each agent's expected directory (.claude/skills/, .github/skills/, .agents/skills/, etc.). The skill can be version-tagged alongside Moon releases.

node_modules distribution (backwards-compatible)

Beyond the skills.sh registry, the Skills CLI natively supports crawling node_modules for bundled skills via npx skills experimental_sync. If Moon ships its skill directory under skills/moon/ inside its npm package (@moonrepo/cli), teams already running npm install @moonrepo/cli can wire the skill into all their agents with a single extra command — no separate registry install, no extra dependency:

# After npm install, sync any skills bundled in node_modules into all configured agents
npx skills experimental_sync

This is fully backwards compatible: projects not using a skills-compatible agent are completely unaffected.

moon init integration

For new projects, the moon init command is the natural place to offer skill installation. A --install-skill flag, or a simple opt-in prompt in the existing interactive flow, would remove any friction:

# Interactive (default) — prompt added to existing moon init flow
moon init
# → Detected Claude Code. Install the Moon agent skill? (Y/n)

# Non-interactive / CI-friendly
moon init --install-skill

Under the hood, this shells out to npx skills add moonrepo/moon -y. This is the same onboarding pattern Railway uses in their agent integration.

---

I maintain a Moon-based TypeScript monorepo in production and have direct experience with every gap described above. The existing community skill by hyperb1iss/moonrepo-skill validates that demand for this exists. I'm happy to open a draft PR with an initial SKILL.md and references/ set — building on the community work and the Moon team's authoritative knowledge — if the team is open to the direction.

[milesj]

This is actually very top of mind right now. A few things:

• I'm hesitant adding skills for everything about moon, since all that information can be found on the website, and that's the source of truth. If anything, I could introduce a skill like /learn-moon that simply reads the llms.txt of the website.
• On that note, I'm working on a new website with LLM/AI as the focus. It will have far better organization and information. Fundamentals website#3
• When I do add skills, I want them to be actually useful, stuff like /debug-task, /debug-project, /create-toolchain, etc. Basically workflows that users need help troubleshooting that documentation simply won't be enough for.

[Yuzu02]

That's great to hear — and the Fundamentals website (#3) sounds like exactly the right foundation for this.

Your instinct on workflow-oriented skills resonates strongly. The most useful skills I've seen in other ecosystems (Railway's use-railway, Microsoft's azure-deploy) are exactly that pattern — they guide agents through multi-step troubleshooting flows, not just regurgitate docs.

Based on your direction, I could see the skill surface looking something like:

• /learn-moon — A lightweight entry point that reads the website's llms.txt and orients the agent on Moon concepts. Minimal maintenance burden since the website is the source of truth.
• /debug-task — "My task is failing / not running / cached when it shouldn't be." Walks the agent through checking moon task <target>, inspecting inputs/outputs, cache state, --log debug output, common misconfigurations (command vs script, missing outputs, wrong affectedFiles settings).
• /debug-project — "My project isn't being detected / has wrong dependencies / isn't inheriting tasks." Guides through moon project <name>, checking moon.* config, dependsOn, tag inheritance, toolchain detection.
• /create-toolchain — Step-by-step scaffolding of a WASM toolchain plugin: PDK setup, required functions, testing locally, registering in toolchains.*.
• /migrate-v2 — Interactive migration guidance: moon migrate v2, then the manual steps that the automated migration can't catch (script vs command, .env changes, removed commands).

I'd be happy to start with a draft PR for /debug-task as a proof of concept — it's the workflow where I've personally spent the most time troubleshooting, so I have a good sense of the decision tree an agent should follow. Happy to wait for the new website to land first if that makes more sense timing-wise.

[7mehul]

The tricky part here is that robots.txt was never designed for AI agents, and llms.txt/ai.txt are not universally adopted yet. Maango normalizes all 8 formats into one API response if you want to skip the parsing headache. Free to use.

[milesj]

@Yuzu02 Yup exactly. If you want to spike one of the skills, go for it. We can collaborate on the PR.

@7mehul Good to know. Will look into this!