> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo-platform/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-platform/_mcp/server. # ETHOS.md > ETHOS.md is the intent layer for a production agent: a Markdown contract other agents use to detect and resolve divergence between developer intent and execution. `ETHOS.md` is the **intent layer** for a production agent. It's a simple, open standard for detecting and resolving divergence between developer intent and agent execution. The goal of `ETHOS.md` is to transform scattered intent into a shared contract that builders, reviewers, and optimizers can use. Code shows implementation. Ethos is the only place that records mission, constraints, success and failure, and what may change. ## Why it exists Critical agent context lives outside the codebase: business objectives, developer intent, success and failure criteria, and safe modification boundaries. Humans rarely write all of that down. An optimizer that only sees code and traces cannot tell a real failure from a trade-off you already accepted. Without an Ethos, every new agent has to rediscover that context, and automated changes are aligned to whatever the traces happen to show. With one, the same file can steer a new build, guide a review of logs and evals, reveal divergence from intent, and keep an optimization loop inside human-set bounds. ## Scattered context, one contract Intent arrives in pieces: * The **codebase** — files, docs, configs, and logic. This is what the agent does today. * **Traces and logs** — telemetry, errors, and metrics. This is how a run looked, not whether that look was acceptable. * **Business goals** — objectives, value, and the result the agent is accountable for. * **Developer intent** — tone, priorities, and the judgment calls that never made it into a ticket. * **Constraints** — limits, policies, and guardrails no change may cross. `ETHOS.md` is the portable snapshot of that contract. Write the intended state, not only the implemented one. Where they differ, say so. ## What it unlocks | It unlocks | Meaning | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Portable context** | Every builder, reviewer, and optimizer starts from the same file instead of reconstructing intent from the repo. | | **Shared contract** | Humans and agents agree on purpose, bounds, and what counts as divergence. | | **Spec-driven creation** | Purpose, goals, and expected behavior are explicit before code exists, so implementation follows intent instead of inferring it later. | | **Safe changes** | Optimization agents know what they may change, what needs approval, and what they must not touch. | | **Recursive updates** | As you clarify intent while reviewing a change or an Insight, the Ethos absorbs it. The file is meant to stay current; a stale Ethos steers the next loop the wrong way. | `Change Scope` is the machine-readable part of "safe changes": each lever is `yes` (allowed), `no` (must not change), or `with-approval`. ## Ethos is not `AGENTS.md` The two files serve different agents. | | `AGENTS.md` | `ETHOS.md` | | ---------------- | ------------------------------------------------ | ------------------------------------------------------------------------- | | When it matters | Any repo a coding agent should navigate | When the repo, or a package in it, *is* an agent | | Job | How to contribute: layout, conventions, commands | Intent, goals, and constraints — the PRD layer optimization agents need | | Typical location | Repository root | Next to the agent (`agents/-ethos/ETHOS.md` on NeMo Platform) | ## What's in the file A Markdown file with front matter. Section bodies stay human-readable; the headings are the outline other agents parse. | Section | Captures | | -------------------- | -------------------------------------------------------------------- | | `Role` | What the agent does, in one concrete sentence. | | `Purpose & Outcomes` | Why it exists, and the result it is judged by. | | `Scope` | Who it serves, in-scope work, and boundaries. | | `Tools` | APIs, tools, and knowledge sources it can use. | | `Harness` | How this agent actually runs. | | `Behavior` | Rules, tone, refusals, and policies. | | `Principles` | How to decide when no rule in `Behavior` covers the case. | | `Success Criteria` | What good production behavior looks like. | | `Trade-offs` | Hard gates, priority order, and unacceptable regressions. | | `Constraints` | Limits no optimization may cross. | | `Evaluation Setup` | How it is tested and measured. | | `Metric Semantics` | What metric names actually mean, and the claims they do not support. | | `Change Scope` | What optimization agents may modify. | | `Vision` | Where the agent is headed, beyond today's scope. | | `Open Questions` | Unknowns to resolve. | ## Creating an ETHOS.md On NeMo Platform, invoke the `nemo-explore` skill to learn about your agent, and gather intent through some Q\&A, then `nemo-ethos` writes `agents/-ethos/ETHOS.md`. You can also author the file by hand. See [Plugins and Skills](/documentation/agents/plugins-and-skills#coding-agent-skills).