ronnasayd/aipp/agent-creator
Claude Code and agent skill by ronnasayd/aipp
- community
Checking that the SKILL.md file is still in the repository.
Create new specialist agents, modify and improve existing agents, and validate agent behavior. Use when users want to create a custom agent from scratch, edit or optimize an existing agent, test an agent against realistic prompts, or improve an agent's description and instructions. Triggers on phrases like "create an agent for X", "make a specialist agent that does Y", "build me an agent for Z", "improve this agent", "update agent instructions", "add a new agent", or whenever a new autonomous specialist role needs to be defined. Always use this skill when the work involves writing or editing .agent.md files, even if the user just says "I need something that specializes in X".
Install
npx vskill@latest install ronnasayd/aipp/agent-creatorSKILL.md
The same SKILL.md was published earlier as ronnasayd/aipp/agent-creator.
Agent Creator
A skill for designing, writing, and iteratively improving specialist agents.
At a high level, the process goes like this:
- Understand what role the agent should play and what it should do autonomously
- Draft the agent persona, instructions, and workflow
- Test it with realistic prompts that simulate how users will actually invoke it
- Evaluate both the agent's behavior and the quality of outputs it produces
- Refine the instructions based on what worked and what didn't
- Repeat until the agent behaves reliably and produces excellent results
Your job is to figure out where the user is in this process and jump in to help them progress. If they say "I want an agent for X", start from scratch. If they already have a draft, go straight to evaluation and iteration.
Key Concepts
Skills vs. Agents
Understanding the distinction helps design better agents:
| Concept | Skill | Agent | |
|---|---|---|---|
| File | SKILL.md | <name>.agent.md | |
| Trigger | Opportunistic (based on description match) | Explicit invocation | |
| Scope | Provides instructions to current Claude | Autonomous specialist running with its own context | |
| Identity | No persona — just a workflow guide | Has a clear persona, expertise, and role | |
| Autonomy | Guides Claude step-by-step | Iterates independently until task is resolved |
Agents are autonomous specialists. They should be self-sufficient, persistent, and iterate until the task is truly done — not hand things back to the user prematurely.
Creating an Agent
Step 1: Capture Intent
Start by understanding what the user wants this agent to do. Extract answers from the conversation if available:
- What domain or specialty should this agent cover? (e.g., security, database, documentation)
- What tasks will it be asked to perform autonomously?
- What are the expected outputs? (code, documents, reports, decisions)
- What tools should it use or have awareness of? (file search, terminal, MCPs, etc.)
- What behavioral expectations exist? (e.g., always document evidence, always test, ask before destructive actions)
- Are there existing agents it should complement or differ from?
If this is being derived from a conversation history, extract context before asking further questions.
Step 2: Research Existing Agents
Before drafting, always check the agents/ directory:
Look for:
- Agents with overlapping domain — to avoid duplication and identify gaps
- Patterns and conventions already established in this workspace
- Descriptions that can serve as inspiration or contrast
Read 2-3 existing .agent.md files relevant to the domain to absorb the established voice and structure.
Step 3: Interview for Depth
Ask targeted questions to fill in gaps:
- What should the agent do if it hits an obstacle? (retry, escalate, document?)
- How much autonomy should it have before asking for confirmation? (especially for destructive actions)
- What documentation sources should it consult on startup? (docs/, README, ADRs, etc.)
- Should it interact with other agents? Which ones?
- What defines "done" for this agent? (success criteria)
Step 4: Write the Agent File
Create the file at agents/<name>.agent.md following the anatomy in the next section.
Save it alongside the other agents so it integrates naturally into the workspace.
Agent Anatomy
Every agent file follows this exact structure:
YAML Frontmatter
Name rules:
- Lowercase, hyphen-separated
- End with
-specialistif it's a domain expert (consistent with existing patterns) - Descriptive of the role, not the technology alone
Good names:
Bad names:
Description (Critical for Discoverability)
The description is the primary mechanism by which Claude selects agents. A weak description means the agent never gets invoked.
Proven template:
Key principles:
- Be specific about when to use it — include concrete trigger contexts, not just abstract role names
- Name the outputs — what does the agent deliver? (reports, fixes, plans, documents)
- State the completion contract — when does the agent consider itself done?
- Be slightly "pushy" — agents tend to be underselected; a description that's assertive about its use cases gets invoked more reliably
Example (good):
Example (weak — avoid):
Instructions Block
Wrap all content in <instructions>...</instructions> tags:
1. Identity & Expertise
Open with a clear role declaration and list of core competency areas:
The capability list anchors the agent's identity and helps it prioritize when tasks overlap multiple domains.
2. Behavioral Requirements
Define the non-negotiables — how the agent should behave regardless of the task:
Adjust these to the specific agent's domain (e.g., a docs agent emphasizes clarity over tool execution; a security agent emphasizes evidence logging).
3. Documentation Sources
Tell the agent where to look for context at startup:
4. Phased Workflow
This is the heart of the agent. Define a numbered, phase-based workflow that takes the agent from "receive task" to "task complete":
Customize phases to the domain. A security agent has reconnaissance and threat modeling phases. A docs agent has usability review phases. Don't use generic phases if specialized ones make more sense.
5. Communication & Interruption Handling
Every agent should handle user interruptions gracefully:
Testing the Agent
After writing the agent draft, design 2-3 realistic test prompts that simulate how users will actually invoke it. These should be:
- Concrete, not abstract — include domain-specific details
- Non-trivial — something that requires multi-step autonomous work
- Varied — cover different aspects of the agent's scope
Good test prompt:
Weak test prompt (too simple):
How to Run Tests
Since agents are autonomous specialists, the best way to test them is to:
- Spawn a subagent using
runSubagentwith the agent's name (if already registered) - OR manually follow the agent's own instructions yourself to simulate a run
- Evaluate the output against the success criteria
For each test run, assess:
| Dimension | Questions | |
|---|---|---|
| Role alignment | Did it stay in character as the specialist? | |
| Autonomy | Did it work without unnecessary hand-holding? | |
| Output quality | Was the output accurate, complete, and useful? | |
| Workflow adherence | Did it follow the phased workflow? | |
| Documentation | Did it document decisions and evidence? | |
| Completion | Did it deliver a clear, actionable result? |
Improving the Agent
After evaluating test runs, identify the most impactful change to make. Common issues and their fixes:
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/agent-creator/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/ronnasayd/aipp/agent-creator)