ethos-write

Files (10)

• BENCHMARK.md
• SKILL.md
• config.yml · evals/
• evals.json · evals/
• explore-notes.md · evals/files/invoice-triage/
• ethos.md · evals/files/router-help/
• ethos.md · references/templates/
• validate_ethos.py · scripts/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

<!-- 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.

   ```bash
   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 `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.

4. **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` =

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills