feat: add agent-creator skill

README.md

@@ -32,7 +32,7 @@ Browse available plugins in [`plugins/`](plugins/).
 ## Extensions Catalog
 
 <!-- BEGIN AUTO-GENERATED CATALOG -->
-This repository contains **2 marketplace(s)** with **45 extensions** (36 skills, 9 plugins).
+This repository contains **2 marketplace(s)** with **46 extensions** (37 skills, 9 plugins).
 
 ### Quick Start
 
@@ -89,11 +89,12 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**41 extensions** (34 skills, 7 plugins)
+**42 extensions** (35 skills, 7 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
 | add-skill | skill | Add (import) an OpenHands skill from a GitHub repository into the current workspace. | — |
+| agent-creator | skill | Create file-based sub-agents as Markdown files — no Python code required. Guides the user through a structured interv... | `/agent-creator` |
 | agent-memory | skill | Persist and retrieve repository-specific knowledge using AGENTS.md files. Use when you want to save important informa... | `/remember` |
 | agent-sdk-builder | skill | Guided workflow for building custom AI agents using the OpenHands Software Agent SDK. Use when you want to create a n... | `/agent-builder` |
 | automation | skill | Create and manage OpenHands automations - scheduled tasks that run in sandboxes. Use the prompt preset to create auto... | — |

marketplaces/openhands-extensions.json

@@ -10,6 +10,20 @@
         "homepage": "https://github.com/OpenHands/extensions"
     },
     "plugins": [
+        {
+            "name": "agent-creator",
+            "source": "./skills/agent-creator",
+            "description": "Create file-based sub-agents as Markdown files — no Python code required. Guides the user through a structured interview and generates a ready-to-deploy .md agent file following the OpenHands SDK specification.",
+            "category": "development",
+            "keywords": [
+                "agent",
+                "sub-agent",
+                "file-based",
+                "markdown",
+                "no-code",
+                "create"
+            ]
+        },
         {
             "name": "add-skill",
             "source": "./skills/add-skill",

skills/agent-creator/README.md

@@ -0,0 +1,104 @@
+# 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](https://docs.openhands.dev/sdk/guides/agent-file-based):
+
+```markdown
+---
+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
+
+| Scope | Primary path |
+|---|---|
+| Project-level | `{project}/.agents/agents/<name>.md` |
+| User-level | `~/.agents/agents/<name>.md` |
+
+> 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](https://docs.openhands.dev/sdk/guides/agent-file-based)
+- [Agent Skills & Context](https://docs.openhands.dev/sdk/guides/skill)
+- [OpenHands Extensions Registry](https://github.com/OpenHands/extensions)

skills/agent-creator/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: agent-creator
+description: >
+  Create file-based sub-agents as Markdown files following the OpenHands SDK format.
+  Guides the user through a structured interview to collect requirements, then generates
+  a ready-to-deploy agent file. Use this skill when the user wants to create, design,
+  or build a new sub-agent, even if they don't use the /agent-creator command.
+triggers:
+  - /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:**
+
+| Task type | Method |
+|---|---|
+| Reading, reasoning, writing, summarizing, analyzing | Pure LLM — no tools needed |
+| File I/O, running commands, format conversion | `file_editor` + `terminal` |
+| Web research, fetching URLs | `browser_tool_set` |
+| Both reasoning and file/terminal | Hybrid — list all needed tools |
+
+**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.

skills/agent-creator/commands/agent-creator.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Create file-based sub-agents as Markdown files following the OpenHands SDK format. Guides the user through a structured interview to collect requirements, then generates a ready-to-deploy agent file. Use this skill when the user wants to create, design, or build a new sub-agent, even if they don't use the /agent-creator command.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS