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.
1---2name: ethos-write3description: 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.4triggers:5 - write the ethos6 - save the design7 - capture what we agreed8 - persist the agent design9 - update the ethos.md10 - write agent ethos11not-for:12 - ethos-explore (use to gather the design before writing the ethos.md)13 - ethos-orchestrate (use to choose between exploring and writing an ethos.md)14compatibility: 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.15license: Apache-2.016user-invocable: true17allowed-tools: Read, Write, Edit, Bash18metadata:19 source: https://skillmd.com/skills/nvidia/ethos-write20---2122<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->23<!-- SPDX-License-Identifier: Apache-2.0 -->2425# Write an agent's ethos.md2627Turn the answers from `ethos-explore` into a durable artifact. The ethos.md is28the contract that people and agents read before they build, evaluate, review,29or change this agent. Without it, each of them has to re-ask everything, and30nothing records what the agent is supposed to do.3132Creating or reviewing an ethos.md does not authorize application changes or imply33that changes will follow. Do not ask for permission to modify prompts, models,34tools, validation code, or workflow structure, or generate sections listing those35permissions. Any workflow that later changes the application36collects the permissions it needs when that work is undertaken. Keep behavioral37constraints and safety boundaries, including approvals the agent needs for its38own actions, in `Behavior` and `Constraints`. Also retain already-confirmed39organizational safety and review policies and their known owners; recording40such a restriction does not grant permission to make a change.4142The ethos.md records the **intended** state of the agent, which is not the same as43the implemented state. The codebase already shows what the agent does. This file44is the only place that records what it is supposed to do, what it must never do,45and how to weigh a win on one metric against a loss on another.4647## Location4849The ethos.md is a local file in the agent's repository, committed alongside50the code it describes. Use the path the user names. Otherwise reuse an51existing ethos.md, including an `ETHOS.md` written by Eval Author 0.1.0. Otherwise write52`ethos.md` at the repository root; in a repository with several agents, put it53at the root of the agent's own package and confirm that path with the user.54The file is the only copy. There is no remote canonical copy to sync.5556## Schema version5758Write `schema_version: 1`. Every canonical body section is required. The59validator rejects a file missing any of those headings. When you have nothing60to say, write `_(none)_` rather than dropping the section.61Version 1 is the only schema version. When a new version ships, its migration62steps belong in this skill.6364The schema is a floor, not a ceiling. Extra `##` headings and extra YAML65front-matter keys are allowed. The parser keeps unknown body sections and66does not fail on unknown front-matter keys. If the user already added custom67sections, preserve them on rewrite. Do not strip custom content to make the68file look strict. This includes a legacy `Change Scope` section: preserve it on69edits unless the user asks otherwise, but do not treat it as authorization for70application changes in this workflow.7172Do not invent content to look complete: `_(none)_` in `Constraints` is honest,73while a fabricated bound actively misleads anyone changing the agent. If the user has no74answer yet, write `_(none)_`, record the gap in `Open Questions`, and move on.7576ethos.md holds durable intent, so keep run-scoped configuration out of it. A spend77ceiling, an experiment count, or a wall-clock limit for a single evaluation78run belongs to the tool that runs it. If a user offers one, record79the standing policy it implies — a production cost ceiling in `Constraints`, or80who approves an overrun — and leave the run limit itself to that tool's config.8182## Hard preconditions8384Before writing anything, the answers carried over from `ethos-explore` must85satisfy one non-negotiable. If it is missing or ambiguous, **stop and route back86to `ethos-explore` for that field only** — do not invent a default.87881. **Role** — one concrete sentence describing the role this agent plays. Vague89 answers ("help with stuff", "answer questions") make the artifact useless90 downstream even though the parser will accept them; push back in91 conversation rather than writing a placeholder.9293The parser cannot catch a vague `Role`, which is why this skill enforces it94upstream: the user sees a clear gap-question instead of a file that validates95and then helps nobody.9697## What you do98991. **Confirm the agent name.** Short and recognizable: `it-helpdesk`,100 `support-triage`, `code-reviewer`. If the user has not named it, propose101 two options based on the role.1021032. **Pre-flight: locate the file.** Resolve `ETHOS_PATH` as described in104 [Location](#location). If a file already exists there, ask the user whether105 to edit it or start over. Read an Eval Author 0.1.0 `ETHOS.md` as the existing ethos.md.106107 ```bash108 find . -maxdepth 4 -iname ethos.md -not -path '*/.git/*' -not -path '*/node_modules/*' 2>/dev/null | grep . || echo "ethos_new"109 ```1101113. **Run a focus check before rendering.** The carried-over answers should be112 mission-led and reviewable, not a raw inventory of implementation details:113114 - `Purpose & Outcomes` and `Success Criteria` must explain mission, user115 value, the measurable result, and the success bar. If they only summarize the116 current code, route back to `ethos-explore` to ask whether the user has117 outside context that is not in the codebase. If no such context exists,118 say the section is inferred from implementation.119 - `Trade-offs` must be decidable. "Balance quality and cost" is not usable;120 a priority order with named hard gates is. If the user has not ranked121 anything, ask for the ranking rather than writing a platitude.122 - `Constraints` must be checkable. Prefer "models must come from the123 internal gateway" over "use approved models." This is also where the124 permitted model and provider set lives; there is no `Model` section,125 because the config already records the model in use and it changes without126 touching this file.127 - `Tools` and `Harness` should be concise. For `Harness`, describe how this128 agent actually runs. Do not pick a named harness from a catalog, and do not129 treat a framework import as a requirement. Group related helpers in130 `Tools` by capability or source when they share credentials, side131 effects, freshness, and failure modes. Keep only details that change how132 downstream agents evaluate behavior.133 - Avoid public shorthand like `AUT` or "agent under test." Use "this agent"134 for the agent being specified. Use "target agent" only when this agent's135 job is explicitly to inspect or modify another agent.1361374. **Render the ethos.md.** Use the template at138 `references/templates/ethos.md` as the starting point. Substitute139 every section from the `ethos-explore` answers. Set front matter as:140 `schema_version` = `1`, `name` = the canonical agent name,141 `created_timestamp` = current UTC timestamp in ISO 8601 form, and `author` =142 the human or coding agent creating the file. Add `owner` when a human or143 team is accountable for the agent's behavioral or safety approvals named in144 `Behavior` or `Constraints`, including a known owner of an already-confirmed145 organizational safety policy.146 Set `updated_timestamp` on edits, not on first write. Evaluation commands147 live in `Evaluation Setup`, not in front matter. Keep the required section148 headers exactly so the file stays parseable. Extra `##` headings after149 (or among) the canonical fourteen are allowed — keep them. The file is150 lightly validated by the bundled `scripts/validate_ethos.py`, which151 checks front matter, schema version, required sections, and duplicate152 sections. It does not reject unknown headings. Section bodies stay markdown153 for agents and humans to read directly.1541555. **Write the file.** Write to `ETHOS_PATH`, creating its directory if needed.156 If an Eval Author 0.1.0 `ETHOS.md` exists in that directory, rename it to `ethos.md`157 before writing, through a temporary name so the rename also works on158 case-insensitive filesystems:159160 ```bash161 DIR=$(dirname "$ETHOS_PATH")162 if ls "$DIR" | grep -qx ETHOS.md; then163 mv "$DIR/ETHOS.md" "$DIR/ethos.md.tmp"164 mv "$DIR/ethos.md.tmp" "$DIR/ethos.md"165 fi166 ```1671686. **Validate.** Run the bundled validator and surface any warnings to the169 user. A failure means the file is malformed; fix the named problem before170 going on. Warnings are not failures — report them so the user can decide171 whether to fill the gap now.172173 ```bash174 python3 "<this skill's directory>/scripts/validate_ethos.py" "$ETHOS_PATH" \175 || echo "ethos_parse_invalid"176 ```1771787. **Show a gut-check, then the file.** Before asking the user to read fourteen179 sections, state your impression of this agent in a short paragraph that180 combines `Role`, `Purpose & Outcomes`, `Scope`, and (when they are not181 `_(none)_`) `Principles` and `Vision`. This is a thin slice so the user can182 tell quickly whether the write got the agent right. Do not use shorthand183 like `AUT` or "agent under test."184185 Shape:186187 > **Gut check.** This is a [role] that exists to [mission / outcome]. It188 > serves [audience] on [in-scope work] and stays out of [out of scope].189 > When the rules run out, it [principle or none]. It is heading toward190 > [vision or none].191 >192 > If that is the wrong agent, say so. Then we can edit before treating193 > this file as signed off.194195 Then print the full file contents and ask: "Does this match what we196 agreed? Edit anything you want to change." If the user edits, repeat197 steps 5–7, including a fresh gut-check.1981998. **Hand off.** Once confirmed, tell the user where the file is and that it is200 ready to commit. It is now the reference for evaluating, reviewing, or201 changing this agent. When intent changes, edit it in place and set202 `updated_timestamp`.203204## Verification205206After writing, both must hold:207208```bash209# Local file present and non-empty.210test -s "$ETHOS_PATH" && echo "local_ok" || echo "local_missing"211212# Passes the bundled validator.213python3 "<this skill's directory>/scripts/validate_ethos.py" "$ETHOS_PATH" \214 && echo "ethos_parse_ok" || echo "ethos_parse_invalid"215```216217Do not announce success until `local_ok` and `ethos_parse_ok` both print, the218gut-check has been shown, and the user has confirmed the contents.219220## If verification fails221222| Symptom | Cause | Recovery |223|---|---|---|224| `local_missing` after write | Wrong working directory or permission denied | Run `pwd`; check the user is in the cloned repo |225| `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 |226| User says "this is wrong" | ethos.md captured the wrong answers | Edit the relevant section in place; re-validate |227| `ethos-explore` was skipped | User invoked `ethos-write` cold | Route back to `ethos-explore` and return here when the conversation is done |228229## What this skill is not230231This skill does not write agent configs, runtime YAML, or code, and does not232register or deploy the agent. The ethos.md is the human-readable design;233machine-readable config stays with the agent's implementation.234235It also does not encode a scoring function. `Trade-offs` records the236developer's intent — hard gates, priority order, unacceptable regressions — in237prose. Turning that into thresholds and weights belongs to whatever evaluates238or changes the agent, not to this file.239240## Gotchas241242- **The template is the source of truth for the canonical outline.** Keep the243 required section headings intact. Extra `##` headings are allowed and must244 be preserved. The bundled validator245 rejects missing or duplicate required sections, but it does not reject246 custom headings. Section bodies remain markdown for humans and agents to247 read directly.248- **ethos.md lives with the agent.** Commit it in the agent's repository, next249 to the code it describes, so every reader finds the same file.250- **Role is a hard requirement.** Do not write the ethos.md without a concrete251 one. Route back to `ethos-explore` for that field only.252- **Honest empty answers belong in the section.** Write `_(none)_` for253 `Constraints` or `Trade-offs` when the user has no answer. Do not invent a254 bound. Record the gap in `Open Questions` as well.255- **`Purpose & Outcomes` cannot be implementation-only by accident.** If goal256 context was not found in the codebase and the user did not provide outside257 context, make that provenance clear instead of letting implementation details258 masquerade as mission. A mission with no stated outcome cannot be measured.259- **Keep public terminology clean.** The generated ethos.md is user-facing. Avoid260 `AUT` and "agent under test"; reserve internal shorthand for test harnesses261 and code comments.262- **Do not duplicate issue tracking into the ethos.md.** Known issues and263 recurring failure patterns belong in the team's issue tracker; the264 ethos.md has no `Known Issues` section, and no `Signals` section either — how a265 given consumer reads evidence is that consumer's configuration, not durable266 intent. Record what a metric cannot support in `Metric Semantics`, and what267 should not count as a failure in `Behavior`.268- **This file is the `ethos.md`.** Agents working on this agent read it but269 should not edit it; only the developer and the developer's coding agent do. Treat it270 as a long-lived contract, not a scratch pad.