---

name: ethos-explore description: Captures what an AI agent is supposed to do — its purpose, boundaries, and success criteria — as a durable snapshot for anyone building, evaluating, reviewing, or changing it. Explores the user's codebase and docs first, then asks one intent question at a time for what source cannot supply. Hands its answers to ethos-write, which writes ethos.md. Use over generic brainstorming when the goal is an agent's ethos.md. triggers:

• design my agent
• what should my agent do
• help me think through the agent
• I want to build an agent
• agent design
• explore the agent
• figure out what my agent needs
• write an ethos.md for my agent
• onboard my existing agent not-for:
• ethos-write (use to write or edit the ethos.md file once explore is done)
• ethos-orchestrate (use to choose between exploring and writing an ethos.md)
• superpowers:brainstorming (use for design work that is not about an agent's intended behavior) compatibility: Dialogue-driven with read-only pre-flight (ls, find, Read); one intent question per message after the codebase scan; at least three questions covering Purpose & Outcomes, Principles, and Vision; safe under any sandbox; works offline; output is a structured conversation handed to ethos-write. license: Apache-2.0 user-invocable: true allowed-tools: Read, Glob, Grep, Bash

---

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

Explore an agent's intended behavior

Capture what the agent should do. Product mission and user goals matter more than implementation inventory. The output of this skill is the data that ethos-write writes into ethos.md — the durable contract that people and agents read before they build, evaluate, review, or change this agent. Underspecified input here leads every one of them to guess at intent from code and traces.

This skill is explore first, then a mandatory intent interview. Scan the codebase and docs, infer implementation-shaped fields, then ask the user for intent source cannot own. Do not skip the interview because the scan looked complete, and do not skip a question because you think you already know the answer. Do not dump the draft ethos.md until that interview has asked at least three questions and received a reply to each.

The division of labor is: infer implementation, ask for intent. Almost everything about what the agent is can be read from source. Nothing about what the developer wants can be. Constraints, trade-offs, principles, mission, and vision live in the user's head, so they are the questions worth spending attention on.

Creating an ethos.md captures intent and authorizes no changes to the agent's application. Do not ask for optimization or change permissions, whether as a separate topic or inside another section. Permission to change code, prompts, models, tools, or evals belongs to the workflow performing that work if the user requests it. Creating an ethos.md implies no such follow-up. Preserve already confirmed organizational safety policies and their known owners, including required security review before shipping a tool with write access. Recording an existing restriction does not grant permission or require a new permission interview.

The schema you are filling

The ethos.md has five base front-matter fields, plus optional updated_timestamp, and fourteen body sections. Every body section is required. One field is a quality gate for handoff: ethos-write is blocked until Role is concrete. For any other canonical section with nothing to say, write _(none)_ rather than dropping the heading.

The fourteen headings are a floor, not a ceiling. Extra ## headings and extra YAML front-matter keys are allowed. Keep them if the user adds them. Do not strip custom sections to make the file look "strict."

Front matter

| Field | Required | Guidance | | :---- | :---- | :---- | | schema_version | yes | Always 1 for new files. ethos-write fills this at write time. | | name | yes | Canonical agent name. Use the directory or workflow name if obvious; ask if not. | | created_timestamp | yes | ISO 8601 timestamp for when the ethos.md is created. ethos-write fills this at write time. | | author | yes | Human or agent that created the ethos.md. ethos-write fills this from the current author context when known; ask only if ambiguous. | | owner | optional | Accountable human or team for runtime action approvals named in Behavior or Constraints; ask only when such an approval needs an owner. Also retain a known owner of an already-confirmed organizational safety policy, without opening a change-permission interview. | | updated_timestamp | conditional | Set on edits. Omit on first write. ethos-write fills this. |

Body sections (in canonical order)

| # | Section | What "good" looks like | | :---- | :---- | :---- | | 1 | Role | One concrete sentence describing the role this agent plays. Example: "answer IT helpdesk questions about VPN, password reset, and software access." Vague answers ("help with stuff") are useless downstream. | | 2 | Purpose & Outcomes | Two labeled parts. Mission: why the agent exists, what user value it provides, and the product or workflow context it serves — not a restatement of implementation mechanics. Outcome: the external result it is accountable for, with the measurable target and who owns that number. A mission with no outcome cannot be measured; an outcome with no mission gets improved in the wrong direction. Say so plainly when the agent is internal tooling with no business metric. | | 3 | Scope | Audience, 3-6 task categories, expected in-scope work, and explicit out-of-scope work/non-goals. | | 4 | Tools | Tools, APIs, and knowledge sources the agent can use, or "Prompt-only." Group related helpers by capability or source. Capture only behaviorally important purpose, credentials/scopes, side effects, freshness, and expected failures. | | 5 | Harness | How this agent actually runs: the loop, tool use, and runtime. Write what is true of this agent. Do not pick a named harness from a catalog, and do not treat a framework import as a requirement. Write _(none)_ if you cannot describe how it runs. | | 6 | Behavior | Behavioral rules and boundaries: refusal/escalation policy, tone, safety/compliance requirements, accepted limitations, and known non-goals. Hard external limits belong in Constraints. | | 7 | Principles | How the agent should decide when no rule in Behavior covers the case: which way to err on an ambiguous request, what it protects even at some cost to the answer, and whose interest wins when the user and the business disagree. Two or three concrete judgment calls. "Helpful, harmless, and honest" is not an answer — it is true of every agent. Write _(none)_ if there is no judgment call beyond Behavior. | | 8 | Success Criteria | What good production behavior looks like, independent of current evals: mission-level outcomes, quality standards, escalation quality, accuracy expectations, and examples of success. Rank them when some matter more. | | 9 | Trade-offs | How to choose when desired outcomes conflict. Needs three things: hard gates never traded away, a priority order over the rest (quality, latency, cost, reliability), and unacceptable compromises. "Balance quality and cost" is not an answer. Write _(none)_ if the user cannot rank them. These are behavioral priorities, not permission to optimize the application. | | 10 | Constraints | Hard external bounds on the agent's operation: approved providers/models/regions, data residency and handling, compliance obligations, production cost ceilings and latency SLOs, and runtime actions that need human sign-off. Retain already-confirmed organizational safety and review policies. Give the current measured figure next to a ceiling when you know it. Usually organizational, which is why the code cannot supply them. Write _(none)_ if unconstrained. Do not collect application-change permissions here. | | 11 | Evaluation Setup | Current validation setup: how to run it, what datasets/checks it uses, what scorers/metrics measure, pass/fail thresholds, and known coverage gaps relative to the success criteria. If no eval suite exists, say so explicitly. | | 12 | Metric Semantics | What ambiguous or load-bearing metric and telemetry field names actually mean, and which claims they do not support. Write _(none)_ when every name means exactly what it says. | | 13 | Vision | Where the agent is headed: an intention beyond today's job, plus one or two concrete use cases it should grow into but does not serve yet. That last part marks what Scope excludes for now rather than on principle. Write _(none)_ rather than pasting a dated backlog. | | 14 | Open Questions | Open facts that affect safe use or evaluation of the agent. Write _(none)_ when there are none. Remove items once answered. Missing application-change permissions are not an Ethos gap. |

The ethos.md records durable intent, not a running list of observed failures. Track known issues and recurring failure patterns where the team tracks bugs.

Pre-flight

Check whether an ethos.md already exists for this agent. Look for ethos.md, including an ETHOS.md written by Eval Author 0.1.0, at the repository root and next to the agent's package. If one is present, ask the user whether they want to edit the existing ethos.md or start over. If they want to edit, route to ethos-write directly.

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

If the repository has an earlier agent spec or design doc, read it as prior answers. Scan the codebase, then still run the intent interview for anything it never answered.

Step 1 — Explore the codebase

Time-box this to ~5 minutes of tool use. Read first, ask second. Greenfield projects will turn up nothing here, which is fine — move to the intent interview and ask for Role first.

1. Find agent definitions and entry points. Look for agent configs, workflow YAMLs, Python agent builders, system prompts, skills, and tool definitions:

   find . -maxdepth 5 -type f \( -name "agent.yaml" -o -name "agent.yml" \) 2>/dev/null
   find . -maxdepth 4 -type f \( -name "*.workflow.yaml" -o -name "*.workflow.yml" \) 2>/dev/null
   find . -maxdepth 4 -type d -name "agents" 2>/dev/null
   

   Then use Glob / Grep to find langgraph, StateGraph, create_react_agent, system_prompt, skills, MCP servers, and tool definitions. Treat any harness or framework name you find as a clue about how the agent runs, not as a value the ethos.md must pick.

2. Find design context. Look for README.md, AGENTS.md, product/design/planning docs, launch notes, and anything in docs/. Read docs that describe goals and user value before implementation details when they look agent-relevant.

3. Map findings to schema fields. As you scan, hold a running mental table of what you can fill from the code/docs. Be honest about confidence: "inferred from system prompt" is different from "confirmed by the user."

4. Note the model only as a constraint. The ethos.md has no Model section. The agent's config already carries the model in use, and it changes without touching the ethos.md. If the scan shows a provider allowlist or pinned model family, carry it into Constraints as a draft to confirm.

   Typical inferences per field:

   • name — directory name, workflow name, or top-level package name.
   • Role — first paragraph of README, system prompt preamble, or top-level docstring. Often partial; usually needs user confirmation.
   • Purpose & Outcomes — mission from product docs, README motivation, system prompt preamble, or workflow