/ethos-orchestrate

name: ethos-orchestrate
description: >-
  Entry point for an AI agent's ethos.md: a durable snapshot of what the agent
  is for, what it must not do, and what success looks like.
  Routes a request to explore and capture intent (ethos-explore), or write or
  edit the file (ethos-write), including renaming an Eval Author 0.1.0 ETHOS.md.
  Owns the standard every ethos sub-flow follows. Use when the user asks "help
  me write an ethos.md", "does my agent have an ethos.md?", "update my agent's
  ethos.md", or when you need to pick between the ethos sub-flows.
triggers:
  - help me write an ethos.md for my agent
  - capture what my agent is supposed to do
  - does this repo have an ethos.md
  - update my agent's ethos.md
  - review my agent's ethos.md
  - rename my ETHOS.md to ethos.md
  - what is an ethos.md
not-for:
  - ethos-explore (use to scan the agent and interview the user for intent)
  - ethos-write (use to render, validate, save, and review the file from agreed answers)
  - eval-author (use to build, audit, or run evaluations; it calls this skill when it needs an ethos.md)
compatibility: >-
  Routing reads the local checkout only. Sub-flows write one local ethos.md;
  validation needs Python 3.10+ and ethos-write's standard-library script.
  Works offline.
license: Apache-2.0
user-invocable: true
allowed-tools: Read Grep Glob

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

Ethos orchestrate

Purpose

Help a developer create and maintain their agent's `ethos.md`. Route each request to the narrow sub-flow that owns it, and carry what is already known into that sub-flow so the user is never asked twice.

Choose the entry route

Locate an existing file first: the user's path, otherwise `ethos.md` at the repository root or at the root of the selected agent's package, otherwise an `ETHOS.md` written by Eval Author 0.1.0.

find . -maxdepth 4 -iname ethos.md -not -path '*/.git/*' -not -path '*/node_modules/*' 2>/dev/null | grep . || echo "no ethos.md yet"

| Starting situation and request | Route | First action and deliverable | |---|---|---| | No ethos.md and the user wants one | [ethos-explore](../ethos-explore/SKILL.md) | Show the path ahead below, then scan and interview. Explore hands off to ethos-write. | | An ethos.md exists and the user names specific changes | [ethos-write](../ethos-write/SKILL.md) | Edit the named sections in place, validate, and review. No new interview. | | An ethos.md exists and intent may have drifted, or the user wants it revisited | [ethos-explore](../ethos-explore/SKILL.md) | Read the file as prior answers; interview only for what changed or is missing. | | An Eval Author 0.1.0 `ETHOS.md` | [ethos-write](../ethos-write/SKILL.md) | Rename it to `ethos.md`; the contents already match the schema. Then handle any requested edits. | | The user wants to know what ethos.md is, or whether one exists | This skill | Explain it, or report what was found and whether it validates. Offer the next route; do not start writing. |

When several apply, take the earliest row that matches. A request phrased as "write the ethos.md" with no prior interview in this conversation still goes through ethos-explore: writing needs intent the code cannot supply.

Show the path ahead

For a fresh request to create an ethos.md, open with this checklist using literal `- [ ]` checkboxes, marking the first step **We're here**:

• [ ] **Explore the agent** — read its code and docs and draft what they establish.
• [ ] **Confirm intent** — answer a few questions the code cannot: purpose, principles, and vision.
• [ ] **Review the draft** — see the whole ethos.md and correct it.
• [ ] **Save and validate** — write the file, check it, and confirm the final contents.

End with "Ready to start?" and wait. On return visits, resume the earliest unfinished step instead of repeating the opening.

The standard

**ethos.md records intent the user confirmed, not intent you inferred.**

• Code, prompts, configs, and docs establish what the agent does today. They

draft `Tools`, `Harness`, `Evaluation Setup`, and similar sections.

• Only the user establishes purpose, principles, vision, trade-offs,

and constraints. An inferred answer is a draft to confirm, never a filled section.

• An honest `_(none)_`, recorded in `Open Questions`, beats a plausible guess.
• The bundled validator establishes structure: front matter, schema version,

and the fourteen required sections. A file that validates can still be wrong; the user's review establishes that it is right.

Vocabulary

| Term | Meaning | |---|---| | ethos.md | The agent's intent snapshot: front matter plus fourteen required `##` sections, schema version 1 | | Section | One required `##` heading from the [template](../ethos-write/references/templates/ethos.md). Extra headings are allowed and preserved | | Inferred | Drafted from source; shown to the user as an option, never final | | Confirmed | Answered or accepted by the user in this conversation | | Legacy file | An `ETHOS.md` written by Eval Author 0.1.0; same schema, earlier file name |

Sub-flows

Load the selected sub-flow skill when its step begins and follow it. This file carries the standard and the routing; the sub-flow carries the steps.

| Sub-flow | Use it to | |---|---| | [`ethos-explore`](../ethos-explore/SKILL.md) | Scan the agent's code and docs, then ask one intent question at a time; hand the agreed answers to ethos-write | | [`ethos-write`](../ethos-write/SKILL.md) | Render the template, save `ethos.md`, run the validator, show a gut-check, and get the user's confirmation; edit an existing file or rename an Eval Author 0.1.0 `ETHOS.md` |

Boundaries

• **Write only the ethos.md.** Never edit the agent's code, prompts, configs,

or evals. The file goes at the user's path or the repository root, and nothing is committed automatically