feat: add agent-creator skill

[Baduc81]

Summary

Adds a new agent-creator skill that guides users through creating
file-based sub-agents via a structured interview workflow.

What this skill does

• Asks the user a series of questions (goal, input, output, tools,
  permission mode, scope, etc.) one at a time
• Classifies the agent type (pure LLM / tool-using / hybrid)
• Drafts a concrete input/output example for confirmation
• Generates a valid .md file following the OpenHands file-based
  agent specification
• Saves to the correct path based on scope (user-level or project-level)

Changes

• skills/agent-creator/SKILL.md — skill definition and interview workflow
• skills/agent-creator/README.md — human-facing documentation
• skills/agent-creator/references/fallback.md — offline fallback spec
• skills/agent-creator/commands/agent-creator.md — auto-generated
• marketplaces/openhands-extensions.json — registered in marketplace

Testing

• uv run pytest -q passes
• uv run python scripts/sync_extensions.py --check passes
• Manually tested interview workflow with multiple agent types

Demo

• Youtube

[VascoSch92]

There are a few points that I believe are missing:

• Documentation & Context: Currently, the agent doesn't know what a "file-based agent" is. We should provide a link to the documentation so the agent can create sub-agents using verified, state-of-the-art methods.

• The Interview Process: The interview flow is great, but there are a few more questions we should ask the user. For instance: "Do you want this to be a project agent or a user agent?" and "What should the permissions be?" These are crucial details, and there may be others we should consider.

• Lifecycle & State: When the agent creates the sub-agent's .md file, do we need to restart the conversation for it to become available? Have you tested this? I suspect a restart might be necessary.

• Demo: Could you record a short video of you triggering the skill to show how it works? It would be helpful to see exactly what to expect.

I think we’re on the right track! We just have a few important things left to address.

Thank you very much! :-)

[Baduc81]

Hi @VascoSch92 @enyst

Thank you for the detailed feedback! Here is how I addressed each point:

Documentation & Context
The skill now fetches the official OpenHands file-based agent documentation
at the start of every session (Step 0):
https://docs.openhands.dev/sdk/guides/agent-file-based

It extracts only the three most relevant sections (Agent File Format,
Frontmatter Fields, Directory Conventions) to avoid bloating the context.
If the fetch fails, it falls back to a local spec in references/fallback.md.

Interview Process
The interview now covers 10 questions including:

• Permission mode (always_confirm / never_confirm / confirm_risky)
• Scope (project-level vs user-level)
• Tools needed, edge cases, gotchas, success criteria, and more

Lifecycle & State
Yes, a conversation restart is required after the agent file is created —
agents are scanned at conversation start, not hot-reloaded. This is now
explicitly stated at the end of the workflow:

"Start a new conversation — agents are scanned at conversation start,
not hot-reloaded."

Skill name
Renamed from agent-spec-designer to agent-creator as suggested.

Demo
I've recorded a short video demonstrating the skill in action and uploaded it to YouTube.
Please watch it here.

[all-hands-bot]

🟡 Acceptable - Solid feature that solves a real problem, but has minor issues to address.

Taste Rating: The skill provides value but the workflow is overly rigid. A few typos and missing test coverage.

[VascoSch92]

Hey @Baduc81

thank you very much.

The video is amazing :-)

Good skill, clear interview workflow and the right guardrails.

A few super small things:

1. Typo: "...when requirements are unclear.e" in the interview rules.
2. fallback.md is missing real frontmatter fields from openhands-sdk/openhands/sdk/subagent/schema.py::KNOWN_FIELDS at minimum max_iteration_per_run, hooks, profile_store_dir. Since the fallback is the authoritative source when the live docs are unreachable, it should match the schema.
3. (super nit): Missing trailing newlines on all three new .md files.

@enyst WDYT?

[all-hands-bot]

Code Review Summary

🟡 Acceptable

The agent-creator skill solves a real problem—helping users create file-based sub-agents without manual Markdown editing. The implementation is well-structured with clear steps, good fallback handling, and proper marketplace integration.

---

[IMPROVEMENT OPPORTUNITIES]

Workflow Flexibility (Lines 41-44, 58-59)

• The rigid "NEVER SKIP" and "Do NOT proceed until confirmed" language may frustrate power users who provide complete information upfront
• The requirement to quote the permission_mode definition after fetching feels like unnecessary verification busywork
• Recommendation: Allow condensing multiple steps when the user provides comprehensive answers upfront

Minor Issues

• Line 39: Typo "unclear.e" → "unclear."
• Line 174: Unclear placeholder <n>.md → <name>.md for clarity

---

[TESTING GAPS]

• No automated tests for the skill functionality
• While LLM-driven interview workflows are hard to test, consider validating:
  • File path generation logic
  • YAML frontmatter formatting
  • Markdown template structure
• The manual testing + YouTube demo is acceptable for initial release

---

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟡 MEDIUM

Risk Factors:

1. External URL dependency: Fetches https://docs.openhands.dev/sdk/guides/agent-file-based (mitigated with local fallback)
2. File system operations: Creates files in user/project directories (well-documented paths)
3. No test coverage: New feature without automated tests (mitigated by manual testing)
4. LLM-generated content: Agent files are generated based on LLM responses (quality depends on interview process)

Recommendation: Safe to merge after addressing typos. The fallback mechanism provides good resilience against external dependency failures. Consider adding basic validation tests in a follow-up PR.

---

VERDICT

✅ Worth merging: Core design is sound, minor improvements suggested. The interview workflow is well thought out, though it could be more flexible for experienced users.

KEY INSIGHT

This skill demonstrates good defensive design with its fallback mechanism and structured interview process. The trade-off between rigid consistency vs. user flexibility leans toward consistency—which may be the right choice for ensuring quality agent generation, but consider allowing power users to short-circuit the process when they provide comprehensive upfront information.

---

This review was created by an AI agent (OpenHands) on behalf of all-hands-bot.

[Baduc81]

Hi @VascoSch92 @enyst

Thanks for the feedback! I've addressed all the points:

• Fixed the typo in the interview rules
• Updated fallback.md to include the required schema fields
• Added trailing newlines to all markdown files

Let me know if anything else needs improvement.

[all-hands-bot]

🟡 Acceptable - Solid feature that solves a real problem with good documentation. The interview-driven workflow is well-structured, though the tone could be less authoritarian.

[enyst]

Looks great to me! Thank you so much for this!

I think maybe we can take this PR in, and we can always iterate in live use?

[openhands-release-bot]

🚀 Released in v0.1.0.

[openhands-release-bot]

🚀 Released in v0.2.0.