/ethos-explore

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, c