nw-command-design-patterns
Best practices for command definition files - size targets, declarative template, anti-patterns, and canonical examples based on research evidence
Install / Use
npx skills add nWave-ai/nWave --skill nw-command-design-patternsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Education & ResearchSupported Platforms
Our assessment of nw-command-design-patterns
nw-command-design-patterns scores 90/100 on our quality scale, 164th of 421 Education & Research skills we index (top 39%).
Its SKILL.md is 9.3 KB long, well organised into 40 sections with 4 code examples: a thorough specification that gives an agent plenty to work with.
It has 617 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so nw-command-design-patterns is actively maintained.
- Our last check on 2026-10-30 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
nw-command-design-patterns compared with similar skills
All 4 of these similar skills score higher than nw-command-design-patterns; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| nw-command-design-patterns (this skill)by nWave-ai | 90 | 617 | 2mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| last30days-skillby mvanhorn | 100 | 68.8k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.9k | 8d ago | CLAUDE.md |
| x402by browser-use | 100 | 121.0k | 4d ago | SKILL.md |
Frequently asked questions
- How do I install nw-command-design-patterns?
- Run
npx skills add nWave-ai/nWave --skill nw-command-design-patterns. The install tabs above show the steps for each supported agent. - Which AI agents does nw-command-design-patterns work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is nw-command-design-patterns safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is nw-command-design-patterns still maintained?
- The repository was last updated about 2 months ago, so nw-command-design-patterns is actively maintained.
Skill content
View source on GitHubname: nw-command-design-patterns description: Best practices for command definition files - size targets, declarative template, anti-patterns, and canonical examples based on research evidence user-invocable: false disable-model-invocation: true
Command Design Patterns
The Forge Model (Gold Standard)
forge.md at 40 lines is the reference dispatcher. Contains: header (wave, agent, overview) | Agent invocation (name + command + config) | Success criteria (checklist) | Next wave handoff | Expected outputs. Every dispatcher should aspire to this pattern.
Command Categories
| Category | Description | Size Target | Examples | |----------|-------------|-------------|----------| | Simple | Direct action, minimal delegation | 40-80 lines | forge, start, version, git | | Dispatcher | Delegates to one agent with context | 40-150 lines | research, review, execute | | Orchestrator | Coordinates multiple agents/phases | 100-300 lines | develop, document |
Declarative Command Template
Commands declare WHAT, not HOW. The agent knows how to do its job.
# DW-{NAME}: {Title}
**Wave**: {WAVE_NAME}
**Agent**: {persona} ({agent-id})
## Overview
One paragraph: what this command does and when to use it.
## Context Files Required
- {path} - {why needed}
## Agent Invocation
@{agent-id}
Execute \*{command} for {parameters}.
**Context Files:**
- {files the orchestrator reads and passes}
**Configuration:**
- {key}: {value} # {comment}
## Success Criteria
- [ ] {measurable outcome}
- [ ] {quality gate}
## Next Wave
**Handoff To**: {next wave or workflow step}
**Deliverables**: {what this command produces}
# Expected outputs:
# - {file paths}
Size Targets and Evidence
Research (Chroma Research, Anthropic context engineering): focused prompts (~300 tokens) outperform full prompts (~113k tokens) | Claude shows most pronounced performance gap | Information buried mid-prompt gets deprioritized ("Lost in the Middle") | Opus 4.6 is proactive/self-directing; verbose instructions cause overtriggering
Targets: Dispatchers 40-150 lines | Orchestrators 100-300 lines | Current average 437 lines; target under 150
The Duplication Triangle
Commands duplicate content in three directions, all waste tokens:
- Command-to-Command: Orchestrator briefings, agent registries, parameter parsing repeated in 5-12 files (~620 lines waste)
- Command-to-Agent: Domain knowledge belonging in agents (~1,300 lines waste). Examples: TDD phases in execute.md, DIVIO templates in document.md, refactoring hierarchies in refactor.md
- Command-to-Self: develop.md embeds other commands inline (~1,000 lines)
Fix: Extract shared content to preamble skill. Move domain knowledge to agents. Have orchestrators reference sub-commands.
Anti-Patterns
| Anti-pattern | Impact | Fix | |---|---|---| | Procedural overload | Step-by-step for capable agents wastes tokens, "lost in the middle" | Declare goal + constraints, let agent apply methodology | | Duplicated briefings | Same orchestrator constraints in every command (30-80 lines each) | Extract to shared preamble, reference once | | Embedded domain knowledge | Refactoring hierarchies, review criteria, TDD cycles in commands | Move to agent definitions or skills | | Aggressive language | "CRITICAL/MANDATORY/MUST" causes overtriggering in Opus 4.6 | Direct statements without emphasis markers | | Example overload | 50+ lines of JSON examples | 2-3 canonical examples suffice | | Inline validation logic | Prompt template validation in command text | Platform/hook responsibility | | Dead code | Deprecated formats, aspirational metrics, old signatures | Remove; version control preserves history | | Verbose JSON state examples | 200+ lines of unused JSON | Show actual format (pipe-delimited), 3 examples max |
When Commands Should Contain Logic vs Delegate
Contain in command (declarative):
- Which agent to invoke
- What context files to read/pass
- Success criteria and quality gates
- Next wave handoff
Delegate to agent:
- Methodology (TDD phases, review criteria, refactoring levels)
- Domain-specific templates/schemas
- Tool-specific config (cosmic-ray, pytest)
- Quality assessment rubrics
Rule: if content describes HOW the agent does its work, it belongs in agent definition or skill, not command.
Canonical Examples
Example 1: Minimal Dispatcher (forge.md pattern, ~40 lines)
# DW-FORGE: Create Agent (V2)
**Wave**: CROSS_WAVE
**Agent**: Zeus (nw-agent-builder)
## Overview
Create a new agent using the research-validated v2 approach.
## Agent Invocation
@nw-agent-builder
Execute \*forge to create {agent-name} agent.
**Configuration:**
- agent_type: specialist | reviewer | orchestrator
## Success Criteria
- [ ] Agent definition under 400 lines
- [ ] 11-point validation checklist passes
- [ ] 3-5 canonical examples included
## Next Wave
**Handoff To**: Agent installation and deployment
**Deliverables**: Agent specification file + Skill files
Example 2: Medium Dispatcher with Context (~80 lines)
# DW-RESEARCH: Evidence-Driven Research
**Wave**: CROSS_WAVE
**Agent**: Nova (nw-researcher)
## Overview
Execute systematic evidence-based research with source verification.
## Orchestration: Trusted Source Config
Read .nwave/trusted-source-domains.yaml at orchestration time, embed inline in prompt.
## Agent Invocation
@nw-researcher
Execute \*research on {topic} [--embed-for={agent-name}].
**Configuration:**
- research_depth: detailed
- output_directory: docs/research/
## Success Criteria
- [ ] All sources from trusted domains
- [ ] Cross-reference performed (3+ sources per major claim)
- [ ] Research file created in docs/research/
## Next Wave
**Handoff To**: Invoking workflow
**Deliverables**: Research document + optional embed file
Example 3: Orchestrator (~200 lines)
Coordinates multiple phases without embedding agent knowledge:
# DW-DOCUMENT: Documentation Creation
**Wave**: CROSS_WAVE
**Agent**: Orchestrator (self)
## Overview
Create DIVIO-compliant documentation through research and writing phases.
## Phases
1. Research phase: @nw-researcher gathers domain knowledge
2. Writing phase: @nw-documentarist creates documentation
3. Review phase: @nw-reviewer validates quality
## Phase 1: Research
@nw-researcher - Execute \*research on {topic}
[Orchestrator reads and passes relevant context files]
## Phase 2: Writing
@nw-documentarist - Create {doc-type} documentation
[Orchestrator passes research output as context]
## Phase 3: Review
@nw-reviewer - Review documentation against DIVIO standards
[Orchestrator passes documentation for review]
## Success Criteria
[Per-phase and overall criteria]
The orchestrator describes WHAT each phase does and WHO does it. The agents know HOW.
Compression Guidelines
When optimizing command files for token efficiency:
Safe to compress:
- Prose descriptions → pipe-delimited
- Verbose explanations → imperative voice
- Filler words ("in order to", "it is important to") → remove
- Related bullet items → single line with
|separators
Never compress:
### Example N:section headers — keep verbatim (eval tools and agents depend on these)- AskUserQuestion decision tree options — these are runtime menu items, not documentation
**Question**:lines in decision points — runtime behavior- Code blocks and YAML — preserve verbatim
- YAML frontmatter — preserve exactly
Compression evidence: Pipe-delimited compression achieves 15-30% token reduction on prose-heavy files. Code-heavy files (PBT skills, code examples) yield <5%. Average across framework: ~7.4% overall.
Orchestrator skill loading section: Commands dispatching sub-agents must include SKILL_LOADING in the Task prompt reminding the agent to read its skills at ~/.claude/skills/nw-{skill-name}/SKILL.md. Without this, sub-agents operate without domain knowledge (the skills: frontmatter is decorative).
Command Installation Format (v2.8+)
Since v2.8.0, commands are installed as skills, not as separate command files. The installer reads from nWave/skills/nw-{command-name}/SKILL.md, NOT from nWave/tasks/nw/{command-name}.md. The legacy tasks/nw/*.md path is still supported but is NOT auto-installed.
When creating a new command, produce THREE files:
-
nWave/skills/nw-{name}/SKILL.md— the installable command skill. Frontmatter MUST include:--- name: nw-{name} description: "One-line description for slash command menu" user-invocable: true argument-hint: "[args] - Example: \"example usage\"" ---Body: the full command definition (same content as the declarative template above).
-
nWave/tasks/nw/{name}.md— legacy task file (kept for backward compat + reference). Same content, simpler frontmatter (justdescription+argument-hint). -
nWave/skills/nw-{name}-methodology/SKILL.md(optional) — deep methodology knowledge for the agent. Frontmatter:--- name: nw-{name}-methodology description: "Methodology knowledge for {name}" user-invocable: false disable-model-invocation: true ---
The skill file (nWave/skills/nw-{name}/SKILL.md) is the PRIMARY deliverable. Without it, the command won't appear in the /nw- menu after installation. The task file is secondary.
Also update nWave/framework-catalog.yaml with the command entry under the appropriate wave section.
Related Skills
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
last30days-skill
68.8kAI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary
Claude-Code-Game-Studios
39.9kTurn Claude Code into a full game dev studio — 49 AI agents, 75 workflow skills, and a complete coordination system mirroring real studio hierarchy.
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
