nWave-ai/nWave / nWave/skills/nw-agent-creation-workflow
nw-agent-creation-workflow
VerifiedDetailed 5-phase workflow for creating agents - from requirements analysis through validation and iterative refinement
Agent Creation Workflow
Overview
Create agents through 5 phases: ANALYZE -> DESIGN -> CREATE -> VALIDATE -> REFINE. Each phase has clear inputs, outputs, and quality gates. Follow "start minimal, add based on failure."
Skill addressing
Classify every skill by how the role needs it:
- Always-needed knowledge belongs in frontmatter
skills:. The installer preloads each declared skill body once, so the agent body never tells the role to load, read or invoke it. - Conditional knowledge stays outside frontmatter. Use the source-aware procedure below to maintain one precise trigger in the generated conditional index; that index also carries the
[SKILL MISSING]protocol. - No handwritten Skill Loading section, table or Load directive in agent bodies. An orphan is an unavailable declared asset or intended conditional knowledge with no reachable trigger, not a missing duplicate directive or an unavailable build-time registry in an installed project.
- Self-description in the skill itself — the skill's
descriptionfrontmatter states when to use it. Knowledge skills withdisable-model-invocation: trueare read on their trigger, never invoked through the Skill tool.
Source-aware conditional-skill procedure
The registry and doc generator are framework build inputs, not installed-project capabilities. First identify the candidate as a framework source agent or an installed/generated artifact.
- Framework source available: establish the actual nWave source checkout and locate its existing
role-skill-loading.yamlregistry andscripts/docgen.py, alongside its agent and skill sources. Read the existing registry schema; declare the conditional skill once under its owning role with the precise trigger, then runpython scripts/docgen.pyfrom that checkout through a permitted execution capability. Inspect the resultingGENERATED:role-skill-loadingregion and referenced skill asset. This is the single conditional index; frontmatter preloads remain untouched. - Installed artifact only, or source/registry/generator capability missing: report exactly which source or execution capability is unavailable. Continue the bounded review or design from the installed generated index and available skill files, but leave registration/regeneration unverified and return the proposed skill/trigger change for the source owner. Do not create a replacement registry in the user's project, hand-edit a generated region, or claim regeneration happened.
- Review boundary: judge whether the installed trigger is precise and its skill reachable. Lack of the undistributed registry alone is not evidence of a broken installed role. Source-provenance verification requires the actual source checkout; record that limit separately.
GOOD vs BAD:
| Shape | Why | |
|---|---|---|
| GOOD | source-aware registration followed by inspection of the generated conditional index | the trigger is authored in its real source and delivered once |
| GOOD | always-needed skill in frontmatter only | the installer preloads it once |
| BAD | frontmatter skill also reloaded by a body directive or table | duplicates already-loaded knowledge |
| BAD | handwritten Skill Loading section or table in the body | a second, drifting index beside the generated one |
Phase 1: ANALYZE
Goal: Understand requirements and determine agent architecture.
Inputs: User requirements, use case description, existing codebase context.
Steps:
- Identify single clear responsibility
- Determine new agent or modification of existing
- Check overlap with existing agents (avoid duplication)
- Classify agent type:
- Specialist: Single-domain expert (most common)
- Reviewer: Validates outputs from another agent (Reflection pattern)
- Orchestrator: Coordinates multiple agents
- Identify required tools (start with Read, Glob, Grep -- add only what's needed)
- Determine if Skills needed (domain knowledge > 50 lines)
Gate: Single responsibility identified. Agent type classified. No overlap.
Output: Requirements summary with agent type, tools list, skill needs.
Phase 2: DESIGN
Goal: Design agent architecture and structure.
Inputs: Requirements summary from Phase 1.
Steps:
- Select a design pattern by applying the already-supplied
nw-design-patternsknowledge - Define role and goal (1-2 sentences each)
- Identify core principles that DIVERGE from Claude defaults:
- What must this agent do differently than Claude naturally would?
- Domain-specific methodology steps
- Non-obvious constraints | Project-specific conventions
- Design workflow (3-7 phases)
- Plan Skills extraction: domain knowledge -> separate Skill | Testing/validation -> separate Skill | Keep workflow and principles in core agent
- Design skill addressing:
- Put only skills needed on every task in frontmatter; the installer preloads them once
- For each conditional skill, plan a precise trigger and apply the source-aware conditional-skill procedure above
- Plan no handwritten Skill Loading section, table or Load directive in the body
- Draft frontmatter:
--- name: {kebab-case-id} description: Use for {domain}. {When to delegate.} model: inherit tools: [{minimum tools needed}] maxTurns: 40 skills: - nw-{skill-name} ---
Gate: Design fits ~200-300 lines (core) + Skills. Pattern selected. Frontmatter drafted.
Output: Agent architecture document (working notes, not deliverable).
Phase 3: CREATE
Goal: Write agent definition file and Skills.
Inputs: Design from Phase 2.
Steps:
-
Create agent
.mdfile:- YAML frontmatter (name, description, tools, model, maxTurns, skills)
- Role + Goal paragraph
- Core Principles (divergences only, 3-8 items)
- Workflow phases
- Critical Rules (3-5, where violation causes real harm)
- Examples (3-5 canonical cases)
- Subagent mode instructions
- Constraints (what agent does NOT do)
-
Create Skill files if needed: each in
nWave/skills/{agent-name}/| YAML frontmatter withnameanddescription| Focused content, 100-250 lines each -
Measure:
wc -l. Target: under 300 lines. -
Apply the source-aware conditional-skill procedure above for each conditional skill. Preserve the single generated index and report missing source or execution capability instead of manufacturing build inputs.
-
Verify: every frontmatter skill exists and is always needed; every intended conditional skill has a reachable precise trigger. Distinguish proposed changes from generated and inspected changes.
Gate: Authorized agent/skill changes delivered; conditional registration is either generated and inspected in the actual source checkout or explicitly pending its named source capability.
Output: Agent .md file + Skill files.
Phase 4: VALIDATE
Goal: Verify agent meets quality standards.
Steps:
- Run
nw-ab-validate-spec: every item ofnw-ab-validation-checklistplus the anti-pattern scan. - Test with representative inputs (Layer 1 testing)
Gate: Every checklist item passes. No anti-patterns.
Output: Validation report (pass/fail per item).
Phase 5: REFINE
Goal: Iteratively improve based on testing feedback.
Steps:
- Address validation failures
- Test with edge cases
- Add instructions ONLY for observed failure modes: wrong decision -> add rule/example | Missed step -> clarify workflow | Over-generated -> add constraint
- Re-measure:
wc -l. If approaching 400 lines, extract to Skills. - Re-validate with
nw-ab-validate-spec.
Gate: All validation passes. Line count within target. Edge cases handled.
Output: Final agent definition, ready for installation.
Quality Gates Summary
| Phase | Gate | Blocks |
|---|---|---|
| ANALYZE | Single responsibility, no overlap | DESIGN |
| DESIGN | Architecture fits size target | CREATE |
| CREATE | File created, under 300 lines | VALIDATE |
| VALIDATE | every nw-ab-validation-checklist item passes | REFINE/Deploy |
| REFINE | Edge cases handled, within target | Deploy |
Naming Conventions
- Agent files:
nw-{name}.mdinnWave/agents/ - Skill files:
{skill-name}.mdinnWave/skills/{agent-name}/ - Reviewer agents:
nw-{name}-reviewer.md - Agent names in frontmatter:
nw-{name}(kebab-case with nw- prefix)
Reviewer Agent Creation (Special Case)
Reviewer agents pair with a primary agent and use the Reflection pattern:
- Set
model: haikuin frontmatter (cost-efficient review) - Use same tools as primary agent (no Write/Edit -- reviewers don't modify)
- Define structured critique output format (YAML)
- Include review rounds, referencing the review-round limit the role bundle prints (nwdes prompt) rather than a hardcoded count
- Define clear approval/rejection criteria
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |