feat(skill): add agent-spec-designer for file-based agent design

[Baduc81]

Summary

This PR introduces a new OpenHands Skill: agent-spec-designer.

The skill enables users to create high-quality, Markdown-based sub-agents through an interview-style workflow, instead of manually writing specifications.

Motivation

Currently, creating file-based agents requires users to:

• Understand the Markdown schema
• Manually define all requirements
• Handle edge cases themselves

This creates friction, especially for new users.

This skill addresses the problem by guiding users step-by-step and ensuring complete, structured agent specifications.

Key Features

• Interview-style requirement gathering
• One-question-at-a-time interaction (reduces cognitive load)
• Mandatory requirement validation:
  • Goal
  • Tasks
  • Input / Output
  • Constraints
  • Edge Cases
  • Success Criteria
  • And other aspects depend on the situation
• Detection of missing or ambiguous requirements
• Smart follow-up questions
• Suggestion of additional design dimensions (tools, execution, validation, etc.)
• Generation of clean, implementation-ready Markdown specs

Example Workflow

1. User triggers:
   /agent-designer

2. Agent asks structured questions

3. Requirements are refined interactively

4. Final agent spec is generated

Impact

• Improves onboarding experience for new users
• Increases quality and consistency of generated agents
• Reduces manual effort and errors
• Encourages best practices in agent design

Files Added

• SKILL.md
• README.md

Notes for Reviewers

• The skill enforces strict requirement completeness before generation
• Designed to be adaptive to user expertise level
• Focused on real-world usability rather than theoretical completeness

[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! :-)

[VascoSch92]

perhaps we should use another name.

Something like: agent-creator

because it is not clear that this skill is helping you creating subagents :-)

I'm saying this becuse you could also use the skill as a backslash command and it should be self explanatoriy wht the skill does.

[enyst]

I wonder, are these necessary or... I don't know, realistic? The sub-agents work within the agent-sdk, with its error handling, memory, etc as it is. So I'm thinking, these are not part of the markdown agent so maybe we don't have to tell the LLM about them 🤔

[Baduc81]

You're right, and thanks for catching this. Most of those dimensions (error handling, memory/state, logging, and performance) are infrastructure concerns owned by the SDK runtime, not by the Markdown agent definition itself. Asking users about them in the interview would be misleading and create noise. I'll remove them.
The two I'd keep in some form are security/privacy (since behavioral guardrails like "refuse PII requests" or "always confirm before deletion" are legitimate prompt-level constraints) and potentially data validation (as input-checking behavior). But I agree these should be framed as behavioral rules, not infrastructure config, and should be optional/advanced rather than surfaced by default.