Ethos Write

NVIDIAOfficialPublished by NVIDIA

Skill
Content generator
Agent tooling
Apache-2.0
Medium risk
Has scripts

From the author

Writes an AI agent's ethos.md — a durable snapshot of its purpose, intended behavior, boundaries, and success criteria — from the answers gathered by ethos-explore. Renders the schema-v1 template, validates the front matter and required markdown sections, saves the file in the agent's repository, and reviews it with the user. Also edits an existing ethos.md. Use over generic planning skills for an agent's ethos.md.

— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

ethos-write creates a standardized, machine-readable, and human-readable ethos.md file that serves as the definitive contract for an AI agent. It transforms design insights into a structured artifact that guides developers, evaluators, and other agents. The skill enforces a specific schema, validates the content, and ensures the agent's intended behavior is clearly documented alongside its codebase. It is designed to be used after gathering design requirements to ensure the agent's mission, constraints, and success metrics are captured in a durable, version-controlled format.

What it does

Generates an ethos.md file using a standardized schema-v1 template.
Validates the file structure, front matter, and required sections.
Updates existing ethos.md files while preserving custom content.
Provides a gut-check summary of the agent's role and purpose for user review.
Ensures the agent's intended state is documented separately from its implementation.
Enforces the inclusion of a concrete role definition before file creation.

When to use it

When you need to create a durable design contract for a new AI agent.
When you need to update the documented purpose or constraints of an existing agent.
When you want to ensure your agent's behavioral boundaries are clearly communicated to other developers or agents.
After completing the design exploration phase to persist the agreed-upon agent architecture.

Advantages

Creates a single source of truth for an agent's intended behavior.
Standardizes documentation across different agents for easier evaluation and review.
Separates durable intent from transient runtime configurations.
Includes automated validation to ensure the documentation remains parseable and complete.
Supports iterative updates while maintaining historical context.

Usage examples

“write the ethos”: The agent prompts for the necessary design details, validates the input, and generates an ethos.md file in the repository root.
“update the ethos.md”: The agent reads the existing file, allows you to modify specific sections, and re-validates the updated document.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/ethos-write/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip ethos-write.zip -d .agents/skills

Documentation by NVIDIA

Write an agent's ethos.md

Turn the answers from ethos-explore into a durable artifact. The ethos.md is the contract that people and agents read before they build, evaluate, review, or change this agent. Without it, each of them has to re-ask everything, and nothing records what the agent is supposed to do.

Creating or reviewing an ethos.md does not authorize application changes or imply that changes will follow. Do not ask for permission to modify prompts, models, tools, validation code, or workflow structure, or generate sections listing those permissions. Any workflow that later changes the application collects the permissions it needs when that work is undertaken. Keep behavioral constraints and safety boundaries, including approvals the agent needs for its own actions, in Behavior and Constraints. Also retain already-confirmed organizational safety and review policies and their known owners; recording such a restriction does not grant permission to make a change.

The ethos.md records the intended state of the agent, which is not the same as the implemented state. The codebase already shows what the agent does. This file is the only place that records what it is supposed to do, what it must never do, and how to weigh a win on one metric against a loss on another.

Location

The ethos.md is a local file in the agent's repository, committed alongside the code it describes. Use the path the user names. Otherwise reuse an existing ethos.md, including an ETHOS.md written by Eval Author 0.1.0. Otherwise write ethos.md at the repository root; in a repository with several agents, put it at the root of the agent's own package and confirm that path with the user. The file is the only copy. There is no remote canonical copy to sync.

Schema version

Write schema_version: 1. Every canonical body section is required. The validator rejects a file missing any of those headings. When you have nothing to say, write _(none)_ rather than dropping the section. Version 1 is the only schema version. When a new version ships, its migration steps belong in this skill.

The schema is a floor, not a ceiling. Extra ## headings and extra YAML front-matter keys are allowed. The parser keeps unknown body sections and does not fail on unknown front-matter keys. If the user already added custom sections, preserve them on rewrite. Do not strip custom content to make the file look strict. This includes a legacy Change Scope section: preserve it on edits unless the user asks otherwise, but do not treat it as authorization for application changes in this workflow.

Do not invent content to look complete: _(none)_ in Constraints is honest, while a fabricated bound actively misleads anyone changing the agent. If the user has no answer yet, write _(none)_, record the gap in Open Questions, and move on.

ethos.md holds durable intent, so keep run-scoped configuration out of it. A spend ceiling, an experiment count, or a wall-clock limit for a single evaluation run belongs to the tool that runs it. If a user offers one, record the standing policy it implies — a production cost ceiling in Constraints, or who approves an overrun — and leave the run limit itself to that tool's config.

Hard preconditions

Before writing anything, the answers carried over from ethos-explore must satisfy one non-negotiable. If it is missing or ambiguous, stop and route back to ethos-explore for that field only — do not invent a default.

Role — one concrete sentence describing the role this agent plays. Vague answers ("help with stuff", "answer questions") make the artifact useless downstream even though the parser will accept them; push back in conversation rather than writing a placeholder.

The parser cannot catch a vague Role, which is why this skill enforces it upstream: the user sees a clear gap-question instead of a file that validates and then helps nobody.

What you do

Confirm the agent name. Short and recognizable: it-helpdesk, support-triage, code-reviewer. If the user has not named it, propose two options based on the role.
Pre-flight: locate the file. Resolve ETHOS_PATH as described in Location. If a file already exists there, ask the user whether to edit it or start over. Read an Eval Author 0.1.0 ETHOS.md as the existing ethos.md.
```
find . -maxdepth 4 -iname ethos.md -not -path '*/.git/*' -not -path '*/node_modules/*' 2>/dev/null | grep . || echo "ethos_new"
```
Run a focus check before rendering. The carried-over answers should be mission-led and reviewable, not a raw inventory of implementation details:
- Purpose & Outcomes and Success Criteria must explain mission, user value, the measurable result, and the success bar. If they only summarize the current code, route back to ethos-explore to ask whether the user has outside context that is not in the codebase. If no such context exists, say the section is inferred from implementation.
- Trade-offs must be decidable. "Balance quality and cost" is not usable; a priority order with named hard gates is. If the user has not ranked anything, ask for the ranking rather than writing a platitude.
- Constraints must be checkable. Prefer "models must come from the internal gateway" over "use approved models." This is also where the permitted model and provider set lives; there is no Model section, because the config already records the model in use and it changes without touching this file.
- Tools and Harness should be concise. For Harness, describe how this agent actually runs. Do not pick a named harness from a catalog, and do not treat a framework import as a requirement. Group related helpers in Tools by capability or source when they share credentials, side effects, freshness, and failure modes. Keep only details that change how downstream agents evaluate behavior.
- Avoid public shorthand like AUT or "agent under test." Use "this agent" for the agent being specified. Use "target agent" only when this agent's job is explicitly to inspect or modify another agent.
Render the ethos.md. Use the template at references/templates/ethos.md as the starting point. Substitute every section from the ethos-explore answers. Set front matter as: schema_version = 1, name = the canonical agent name, created_timestamp = current UTC timestamp in ISO 8601 form, and author = the human or coding agent creating the file. Add owner when a human or team is accountable for the agent's behavioral or safety approvals named in Behavior or Constraints, including a known owner of an already-confirmed organizational safety policy. Set updated_timestamp on edits, not on first write. Evaluation commands live in Evaluation Setup, not in front matter. Keep the required section headers exactly so the file stays parseable. Extra ## headings after (or among) the canonical fourteen are allowed — keep them. The file is lightly validated by the bundled scripts/validate_ethos.py, which checks front matter, schema version, required sections, and duplicate sections. It does not reject unknown headings. Section bodies stay markdown for agents and humans to read directly.
Write the file. Write to ETHOS_PATH, creating its directory if needed. If an Eval Author 0.1.0 ETHOS.md exists in that directory, rename it to ethos.md before writing, through a temporary name so the rename also works on case-insensitive filesystems:
```
DIR=$(dirname "$ETHOS_PATH")
if ls "$DIR" | grep -qx ETHOS.md; then
  mv "$DIR/ETHOS.md" "$DIR/ethos.md.tmp"
  mv "$DIR/ethos.md.tmp" "$DIR/ethos.md"
fi
```
Validate. Run the bundled validator and surface any warnings to the user. A failure means the file is malformed; fix the named problem before going on. Warnings are not failures — report them so the user can decide whether to fill the gap now.
```
python3 "<this skill's directory>/scripts/validate_ethos.py" "$ETHOS_PATH" \
  || echo "ethos_parse_invalid"
```
Show a gut-check, then the file. Before asking the user to read fourteen sections, state your impression of this agent in a short paragraph that combines Role, Purpose & Outcomes, Scope, and (when they are not _(none)_) Principles and Vision. This is a thin slice so the user can tell quickly whether the write got the agent right. Do not use shorthand like AUT or "agent under test."
Shape:
Gut check. This is a [role] that exists to [mission / outcome]. It serves [audience] on [in-scope work] and stays out of [out of scope]. When the rules run out, it [principle or none]. It is heading toward [vision or none].
If that is the wrong agent, say so. Then we can edit before treating this file as signed off.
Then print the full file contents and ask: "Does this match what we agreed? Edit anything you want to change." If the user edits, repeat steps 5–7, including a fresh gut-check.
Hand off. Once confirmed, tell the user where the file is and that it is ready to commit. It is now the reference for evaluating, reviewing, or changing this agent. When intent changes, edit it in place and set updated_timestamp.

Verification

After writing, both must hold:

# Local file present and non-empty.
test -s "$ETHOS_PATH" && echo "local_ok" || echo "local_missing"

# Passes the bundled validator.
python3 "<this skill's directory>/scripts/validate_ethos.py" "$ETHOS_PATH" \
  && echo "ethos_parse_ok" || echo "ethos_parse_invalid"

Do not announce success until local_ok and ethos_parse_ok both print, the gut-check has been shown, and the user has confirmed the contents.

If verification fails

Symptom	Cause	Recovery
`local_missing` after write	Wrong working directory or permission denied	Run `pwd`; check the user is in the cloned repo
`ethos_parse_invalid`	ethos.md malformed — missing front matter, missing required section, duplicate section, or bad schema version	Read the parser error; fix the named section in place; do not silently work around
User says "this is wrong"	ethos.md captured the wrong answers	Edit the relevant section in place; re-validate
`ethos-explore` was skipped	User invoked `ethos-write` cold	Route back to `ethos-explore` and return here when the conversation is done

What this skill is not

This skill does not write agent configs, runtime YAML, or code, and does not register or deploy the agent. The ethos.md is the human-readable design; machine-readable config stays with the agent's implementation.

It also does not encode a scoring function. Trade-offs records the developer's intent — hard gates, priority order, unacceptable regressions — in prose. Turning that into thresholds and weights belongs to whatever evaluates or changes the agent, not to this file.

Gotchas

The template is the source of truth for the canonical outline. Keep the required section headings intact. Extra ## headings are allowed and must be preserved. The bundled validator rejects missing or duplicate required sections, but it does not reject custom headings. Section bodies remain markdown for humans and agents to read directly.
ethos.md lives with the agent. Commit it in the agent's repository, next to the code it describes, so every reader finds the same file.
Role is a hard requirement. Do not write the ethos.md without a concrete one. Route back to ethos-explore for that field only.
Honest empty answers belong in the section. Write _(none)_ for Constraints or Trade-offs when the user has no answer. Do not invent a bound. Record the gap in Open Questions as well.
Purpose & Outcomes cannot be implementation-only by accident. If goal context was not found in the codebase and the user did not provide outside context, make that provenance clear instead of letting implementation details masquerade as mission. A mission with no stated outcome cannot be measured.
Keep public terminology clean. The generated ethos.md is user-facing. Avoid AUT and "agent under test"; reserve internal shorthand for test harnesses and code comments.
Do not duplicate issue tracking into the ethos.md. Known issues and recurring failure patterns belong in the team's issue tracker; the ethos.md has no Known Issues section, and no Signals section either — how a given consumer reads evidence is that consumer's configuration, not durable intent. Record what a metric cannot support in Metric Semantics, and what should not count as a failure in Behavior.
This file is the ethos.md. Agents working on this agent read it but should not edit it; only the developer and the developer's coding agent do. Treat it as a long-lived contract, not a scratch pad.

Files

ATTRIBUTION.mdAdded by AutoGineer821 B
BENCHMARK.md7.6 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md14.1 KiB
evals/config.yml331 B
evals/evals.json4.6 KiB
evals/files/invoice-triage/explore-notes.md2.5 KiB
evals/files/router-help/ethos.md3.6 KiB
references/templates/ethos.md12.2 KiB
scripts/validate_ethos.pyScript3.8 KiB
skill-card.md4.5 KiB
skill.oms.sig5.7 KiB

references/templates/ethos.md

schema_version: 1 name: <canonical-agent-name> created_timestamp: <ISO 8601 creation timestamp, e.g. 2026-06-02T20:00:00Z> updated_timestamp: <ISO 8601 timestamp of the last edit; omit on first write> author: <human or agent that created this ethos.md> owner: <accountable human or team for the agent's behavioral or safety approvals; omit if unowned>

ethos.md: <name>

This file is the agent's ethos.md — a snapshot of the intended behavior, capabilities, validation setup, and boundaries for this agent. People and agents read it before they build, evaluate, review, or change this agent. Keep it accurate; stale entries here lead them to the wrong conclusions. Creating or reviewing this file does not authorize application changes or imply that changes will follow. A workflow that changes the application collects any required permissions when that work is undertaken.
The layout below is lightly parseable by ethos-write: front matter and the required ## section headers are machine-checked, while section bodies stay markdown for humans and agents to read directly.
Write the intended state, not just the implemented state. Where the two differ, say so. The code already shows what the agent does; this file is the only place that records what it is supposed to do.
Every canonical body section is required. Parsing fails if a required ## heading is missing. When you have nothing to say, write _(none)_ rather than dropping the section. An honest empty answer is better than a fabricated one.
Extra ## headings and extra YAML front-matter keys are allowed. Add them when your use case needs a field this outline does not cover. The parser does not reject custom keys. Do not delete them to look strict.
This file records durable intent, so keep run-specific settings out of it. A spend ceiling or experiment count for one evaluation run belongs in that tool's own config, not here.
Section rules:
Bullet sections (Open Questions): list items only. If the list is empty, write _(none)_ instead of leaving the section blank.
Labeled-bullet sections (Scope): - Label: value lines only. No prose, no blank-line-separated paragraphs. For list-valued labels inside Scope, separate items with semicolons, or write _(none)_.
Free-form sections (Role, Purpose & Outcomes, Tools, Harness, Behavior, Principles, Success Criteria, Trade-offs, Constraints, Evaluation Setup, Metric Semantics, Vision): any markdown. Tools accepts a markdown table or the literal string Prompt-only.

Role

Purpose & Outcomes

<the mission and the result it is judged by, in that order. Keeping them in one section is deliberate: a purpose with no outcome cannot be measured, and an outcome with no purpose gets improved in the wrong direction.

Mission. One or two short paragraphs: why the agent exists, what user value it provides, which product or workflow it belongs to, and the decision or business context it supports. Use context from outside the codebase when the user provides it, and say so plainly when this is inferred from code alone.

Outcome. The external result the agent is accountable for, stated so someone outside the team could tell whether it worked. Give the measurable target where one exists and who owns that number. This is what the agent earns its keep by improving, and what any change to the agent weighs against cost and latency.

Example: "Ships inside the Acme onboarding flow to get a new developer from signup to a working API call without human help. Success is cutting median time-to-first-successful-request from 40 minutes to under 15, without raising support ticket volume. Owner: growth team."

When the agent is internal tooling with no business metric, say that outright rather than inventing one.>

Scope

Audience: <who talks to it — internal employees, external customers, developers, etc.>
Categories: <3-6 task buckets, separated by semicolons; e.g. VPN; password reset; software access>
In scope: <capabilities, user intents, or situations the agent is expected to handle; semicolon-separated or _(none)_>
Out of scope: <capabilities, user intents, or situations the agent should not handle; semicolon-separated or _(none)_>

Tools

<tools, APIs, and knowledge sources the agent can use, or the literal string Prompt-only. if none. Group related helpers by capability or source instead of listing every low-level method. Capture only behaviorally important purpose, credentials or scopes, side effects, data freshness, expected failures, and anything an agent reviewing a trace should know when deciding whether it shows bad agent behavior or a normal tool/source limitation.>

Tool or source	Purpose	Credentials/scopes	Side effects	Freshness / expected failures
current_datetime	clock for time-sensitive answers	none	none	current at call time

Harness

<how this agent actually runs. Describe the loop, how it calls tools, and where it executes. Write what is true of this agent. Do not pick a name from a harness catalog, and do not treat a framework import as a requirement.

Useful things to cover when they apply:

How model turns, tool calls, and stop conditions are orchestrated
How tools are chosen, executed, and returned
How context, memory, and session state are kept
Safety, sandbox, or permission controls around actions
How you observe and verify a run
The runtime, such as a service, CLI, notebook, hosted agent, or workflow

Write _(none)_ if you cannot describe how this agent runs.>

Behavior

Principles

<how this agent should decide when no rule in Behavior covers the case. Rules run out; this section is what a downstream agent falls back on.

Write the judgment calls, not the personality. "Prefer saying I don't know over a confident guess, because a wrong answer here costs a user their afternoon" is usable. "Helpful, harmless, and honest" is not — it is true of every agent and tells a reader nothing.

Two or three of these is plenty. Good candidates:

Which way to err when the request is ambiguous: ask, assume, or refuse.
What the agent protects even when it makes the answer worse — a source citation, an audit trail, an explicit uncertainty flag.
Whose interest wins when the user's request and the business goal disagree.

Keep concrete rules in Behavior and metric weighting in Trade-offs. This section is only for judgment where neither applies. Write _(none)_ if there is no judgment call beyond those two.>

Success Criteria

<what good production behavior looks like for this agent, independent of the current eval suite. Lead with mission-level outcomes and user goals, then capture quality standards, escalation quality, accuracy expectations, and representative examples of successful behavior. Rank them if some matter more than others.

Keep this section about quality and outcomes. Latency and cost belong elsewhere: a production ceiling is a Constraints entry, and how to weigh speed against quality is a Trade-offs entry.>

Trade-offs

<how the agent should prioritize when desired outcomes conflict. State the behavioral priorities that guide the agent and its evaluators.

State three things:

Hard gates. Qualities that are never traded away, at any gain elsewhere. Correctness and safety usually live here.
Priority order. Rank the remaining goals — task quality, latency, cost, reliability, coverage — so competing outcomes can be judged.
Unacceptable compromises. Outcomes that must not get worse even when another improves, and how much variation is acceptable if some slack is fine.

Example: "Answer correctness is a hard gate; never trade it. Then, in order: p95 latency under 10s, cost per session, then token efficiency. A 5% cost increase is acceptable for a 2-point correctness gain. Escalation accuracy must never regress; it is how users trust the agent."

Keep this at the level of intent; do not write a scoring function or grant permission to optimize the application here.>

Constraints

<hard external bounds the agent must respect in operation. These are usually organizational rather than technical, which is why source alone cannot establish them. Record behavioral and safety boundaries here; permissions to modify the application belong to the workflow undertaking those changes.

Cover whichever apply:

Approved providers and models: which vendors, endpoints, regions, and model families the agent may use. Name the deployment mode where it is fixed, such as self-hosted only. State the permitted set rather than the model in use today, which the agent config already carries and which changes without touching this file.
Data handling: residency, retention, redaction, and what may not leave a boundary or enter a prompt.
Compliance and policy: regimes the agent operates under and the audit or disclosure obligations that follow.
Production ceilings: maximum cost per run or session and latency SLOs the deployed agent must respect. Where you know the current measured figure, give it alongside the ceiling — "p95 is 4.1s today against a 6s SLO" tells a reader how much headroom there is, where the ceiling alone does not. Write _(unmeasured)_ rather than guessing.
Action approvals: actions the agent must escalate for human sign-off during operation, and who signs.

Retain already-confirmed organizational safety and review policies, such as security review before shipping a tool with write access, and their known owners. Do not turn these restrictions into a new change-permission interview or infer permission to modify the application from them.

Example: "Models must come from the internal inference gateway; no direct third-party API calls. Customer data must not leave the EU. Cost must stay under $0.08 per session. The agent must obtain human approval before issuing a refund."

Write _(none)_ only if you are genuinely unconstrained.>

Evaluation Setup

Metric Semantics

<what your metric and telemetry field names actually mean, and the claims they do not support. A downstream agent that guesses a field's meaning from its name will produce confident, wrong findings.

Use a row per field that is ambiguous, easy to misread, or load-bearing in a decision. Skip the obvious ones. A known-broken or known-noisy field belongs here too: saying what it cannot support is the cheapest way to stop an analyst re-reporting the same non-issue.>

Field or signal	Meaning	How consumers may use it
<e.g. `score`>	<what the number actually measures, and its source>	<the claim it supports, and the claim it does not>

Use _(none)_ if every metric name means exactly what it says.

Vision

<where this agent is headed, so a change that fits the direction is not judged only against today's scope.

Intention. <what the agent is ultimately for, beyond the job it does today. One or two sentences.>

Target use cases. <one or two concrete scenarios the agent should grow into but does not serve yet. These are the cases Scope calls out of scope *for now*, which is different from out of scope on principle — the distinction stops a change from hardcoding around a direction you already know is coming.>

<future use case>

Keep this durable. A dated backlog belongs in your tracker, because a roadmap that goes stale makes the whole file less trusted. Write _(none)_ rather than filling this with next quarter's tickets.>

Open Questions

<unresolved fact that affects safe use or evaluation of the agent; remove once answered>

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Claude Code frontmatter, Needs Python

The author says: Writes one local markdown file, `ethos.md` at the repository root unless the user names another path; validation needs Python 3.10+ and the bundled standard-library script; works offline; safe under any sandbox; idempotent if user confirms overwrite.

Security

What our scanner noticed· Medium risk

Phrasing that asks for actions without confirmation
Large base64-encoded blobs
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

NVIDIA

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/ethos-write · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download ethos-write.zip