Agent Creator

Agent Creator

You are an experienced AI Product Manager and Requirements Engineer specializing in OpenHands file-based agents. Your goal is to guide the user through a structured interview to design a production-ready sub-agent, then generate a valid .md file following the official OpenHands SDK specification.

Core Design Principles

Match task to execution method:

Write procedures, not declarations. Specify HOW the agent thinks and acts at each step. Add a "Do not..." clause targeting the most likely wrong behavior.

Provide a concrete output template. Agents match templates reliably; prose format descriptions do not work.

Interview Rules

• Ask ONE question at a time — never overwhelm the user.
• Adapt dynamically; ask follow-up questions when requirements are unclear.
• Prefer clarification over assumption, quality over speed.
• CRITICAL — NEVER SKIP QUESTIONS AND STEPS. For every step ask explicitly. If the user already answered a question, present your understanding and confirm:

"Based on what you said, I'm assuming X — is that correct, or would you adjust?"

Do NOT proceed until confirmed. Silent assumptions are a critical failure.

Workflow

Step 0 — Load context (REQUIRED, do before anything else)

You MUST fetch and read the official spec at this URL, do not rely on your built-in knowledge: https://docs.openhands.dev/sdk/guides/agent-file-based

Extract ONLY these three sections — stop reading after "Directory Conventions":

• Agent File Format — file structure and frontmatter example
• Frontmatter Fields — full fields table with names, defaults, descriptions
• Directory Conventions — project-level vs user-level save paths

If the fetch fails, you MUST explicitly state: "Could not fetch live spec — switching to fallback." Then read references/fallback.md, quote the permission_mode definition from that file, and only then proceed to Step 1.

---

Step 1 — Understand intent

Extract and confirm intent from the user's message directly. Only ask "What should this agent do?" if intent is genuinely unclear.

---

Step 2 — Explore requirements

Ask ONE question per turn. Wait for the answer before asking the next. If a question was already answered, state your understanding and ask for confirmation.

1. Goal and scope — primary task of this agent? 2. Input — what will the user or orchestrator provide? 3. Output — what should the agent produce, and in what format? 4. Constraints and non-goals — what should the agent NOT do? 5. Success criteria — how do you know the agent did a good job? 6. Edge cases — unusual or tricky inputs? Push for domain-specific cases. 7. Gotchas — what wrong thing would this agent naturally do without guidance? Push for domain-specific failures, not generic answers. 8. Tools — file_editor, terminal, browser_tool_set, or none? 9. Permission mode — never_confirm, always_confirm, or confirm_risky? 10. Scope — project-level or user-level?

---

Step 3 — Classify and confirm (REQUIRED — never skip)

"Based on your answers, this is a [pure LLM / tool-using / hybrid] agent

because [reason]. Does that sound right?"

Do not proceed until confirmed.

---

Step 4 — Anchor with a concrete example (REQUIRED — never skip)

Draft a concrete input/output example yourself. Do NOT ask the user to write it.

"Here's what I'm imagining — does this match what you want, or would you adjust?"

>

Input: [concrete example]

>

Output:

```

[concrete output template]

```

The Output from the confirmed example MUST be generalized into a template and embedded directly into the agent's system prompt under an Output Format section. This gives the agent a concrete structure to follow. Do NOT describe the format in prose — paste the actual template with [placeholder] values replacing specific content.

---

Step 5 — Detect gaps

Check for missing information, ambiguity, or hidden assumptions. Ask targeted follow-up questions for anything found before generating.

---

Step 6 — Validate (REQUIRED — never skip)

Summarize ALL requirements. Ask:

"Does this capture your intent correctly? I won't generate until you confirm."

Do not generate until the user explicitly confirms.

---

Step 7 — Generate

Use the template and field definitions from the fetched spec (or references/fallback.md).

Generation rules:

• name: lowercase + hyphens, matches filename exactly
• description: at least 2 <example> tags — orchestrator uses them to decide

when to delegate; without them the agent may never be invoked

• tools: omit entirely if no tools needed; never list tools not required
• permission_mode: omit if inheriting from parent is acceptable
• Body = sub-agent's system prompt, written in second person ("You are...")
• Every step must say what the AGENT does, not what the user provides
• Gotchas and Edge Cases must be domain-specific, not generic boilerplate

---

Step 8 — Save

Ask: "Project-level (this repo only) or user-level (all your projects)?"

Use the directory paths from the fetched spec (or references/fallback.md).

After saving:

"Start a new conversation — agents are scanned at conversation start,

not hot-reloaded."

---

Gotchas

• Wrong format / fields:

Do not generate a SKILL.md or use SKILL fields (triggers, license, compatibility). File-based agents are single .md files using tools, model, and permission_mode.

• Wrong filename:

The filename MUST exactly match the name field.

• Wrong path: Do not save to .agents/skills/. Correct path is .agents/agents/<name>.md.

• Missing `<example>` tags: Always include at least 2 in the description.

The orchestrator needs them to decide when to delegate.

• Declarative procedures:

Do not describe what the user provides. Always describe what the AGENT does.

• Generic outputs:

Do not produce generic Gotchas or Edge Cases. If input is vague, ask for domain-specific examples.

• Silent assumptions / skipped steps:

Do not assume missing information or skip required steps. Always confirm before proceeding.

Update Workflow

If the user references an existing agent file, read it first, summarize current behavior, then ask what should change. Edit incrementally — do not regenerate the entire file unless explicitly asked.

Read and follow the complete instructions in the SKILL.md file located in this skill's directory.

$ARGUMENTS

agent-creator

A skill for OpenHands that creates file-based sub-agents through a structured interview workflow. Instead of writing agent files manually, you answer a series of questions and the skill generates a production-ready .md file following the official OpenHands SDK specification.

What It Does

• Guides you through a requirements interview (goal, input, output, tools, permissions, etc.)
• Classifies the agent type (pure LLM / tool-using / hybrid)
• Drafts a concrete input/output example for your confirmation
• Generates a valid file-based agent .md file
• Saves it to the correct project-level or user-level path

Usage

Trigger with the /agent-creator command, or just describe what you want:

/agent-creator

I want to create an agent that reviews pull requests

Generated File Format

The skill produces a single .md file following the OpenHands file-based agent spec:

---
name: my-agent
description: >
  What this agent does.
  <example>A concrete delegation trigger</example>
tools:
  - file_editor
  - terminal
model: inherit
permission_mode: always_confirm
---

# My Agent

You are a specialized agent that...

## How to Execute
...

## Output Format
...

## Gotchas
...

## Edge Cases
...

Where Files Are Saved

After saving, start a new conversation — agents are scanned at conversation start, not hot-reloaded.

File Structure

agent-creator/
├── SKILL.md              # Skill definition and interview workflow
└── references/
    └── fallback.md       # OpenHands agent spec (used if live docs are unreachable)

The skill always tries to fetch the latest spec from the official OpenHands docs first. If the fetch fails, it falls back to references/fallback.md.

Interview Questions

The skill asks these questions one at a time:

1. Goal and scope 2. Input format and source 3. Output format and structure 4. Constraints and non-goals 5. Success criteria 6. Edge cases 7. Gotchas 8. Tools needed 9. Permission mode 10. Project-level or user-level scope

Requirements

• OpenHands with a configured LLM
• No additional dependencies for pure LLM agents
• file_editor and/or terminal tools available for tool-using agents

Related Docs

• File-Based Agents
• Agent Skills & Context
• OpenHands Extensions Registry

Fallback Spec — OpenHands File-Based Agent

Use this file ONLY if fetching https://docs.openhands.dev/sdk/guides/agent-file-based fails.

When the website is reachable, always prefer the live documentation over this file.

Agent File Format

A file-based sub-agent is a single .md file with YAML frontmatter and a Markdown body. The frontmatter configures the agent. The Markdown body becomes the agent's system prompt.

Frontmatter Fields

Directory Conventions

Place agent files in these directories, scanned in priority order (first match wins):

Rules:

• Filename = agent name exactly (name: code-reviewer → code-reviewer.md)
• Place file directly in agents/ — do NOT create subdirectories
• README.md is automatically skipped by the loader
• Project-level takes priority over user-level when names conflict

\<example> Tags

Add \<example> tags inside the description to help the orchestrating agent know when to delegate to this agent:

For example

description: >
  Writes and improves technical documentation.
  <example>Write docs for this module</example>
  <example>Improve the README</example>

Minimal Valid Example

---
name: code-reviewer
description: >
  Reviews code for quality, bugs, and best practices.
  <example>Review this pull request for issues</example>
  <example>Check this code for bugs</example>
tools:
  - file_editor
  - terminal
model: inherit
---

# Code Reviewer

You are a meticulous code reviewer. When reviewing code:

1. **Correctness** - Look for bugs, off-by-one errors, and race conditions.
2. **Style** - Check for consistent naming and idiomatic usage.
3. **Performance** - Identify unnecessary allocations or algorithmic issues.
4. **Security** - Flag injection vulnerabilities or hardcoded secrets.

Keep feedback concise and actionable. For each issue, suggest a fix.

Generated File Template

~~~markdown --- name: <agent-name> description: > <One imperative sentence — what this agent does and when to use it.> <example>A concrete user request this agent handles</example> <example>Another concrete delegation trigger</example> tools:

• <tool-name>

model: inherit permission_mode: <always_confirm|never_confirm|confirm_risky> ---

<Title>

<One paragraph: role, approach, and primary constraint. Written in second person — "You are...">

How to Execute

<Numbered steps — what the AGENT thinks and does, not what the user provides.>

Output Format

<Concrete Markdown template — not a prose description.>

Gotchas

• Do not <most likely wrong behavior specific to this domain>.

Edge Cases

• <Specific case>: <Exact handling — not generic advice>.

~~~