/ethos-write

name: ethos-write
description: 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.
triggers:
  - write the ethos
  - save the design
  - capture what we agreed
  - persist the agent design
  - update the ethos.md
  - write agent ethos
not-for:
  - ethos-explore (use to gather the design before writing the ethos.md)
  - ethos-orchestrate (use to choose between exploring and writing an ethos.md)
compatibility: 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.
license: Apache-2.0
user-invocable: true
allowed-tools: Read, Write, Edit, Bash

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. --> <!-- SPDX-License-Identifier: Apache-2.0 -->

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.

1. **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

1. **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.

2. **Pre-flight: locate the file.** Resolve `ETHOS_PATH` as described in [Location](#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"

3. **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