Agent skill
nw-ai-workflow-tutorials
AI workflow tutorial patterns — non-deterministic output handling, outcome-based verification, and agent workflow step design
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/nw-ai-workflow-tutorials
SKILL.md
AI Workflow Tutorial Patterns
Tutorials for AI-powered tools face a unique challenge: output is non-deterministic. Traditional tutorials show exact expected output; AI workflow tutorials define success by outcome.
The Non-Determinism Contract
State this early in any AI workflow tutorial:
> **AI output varies between runs.** Your output will look different from
> the examples in this tutorial. That is normal. We define success by
> what your code *does*, not what the agent *says*.
Timing Expectations
AI agents work in cycles with processing pauses. Users interpret silence as failure. Always set timing expectations:
## Step 3: Let the Agent Work (~5 minutes)
\`\`\`
/nw:deliver "feature description"
\`\`\`
This takes 3-5 minutes. The agent works in phases with 20-60 second
pauses between visible output. This is normal processing, not a hang.
Provide a "is it stuck?" diagnostic:
> **If you see no output for 2+ minutes**: Check the status bar at
> the bottom of Claude Code. A pulsing indicator means it is still
> working. If the indicator is gone, press Enter to prompt it.
Output Reading Guide
Teach users to read agent output by annotating a realistic example:
### Reading the Output
You will see phases scroll by. Here is what each means:
\`\`\`
● nw-solution-architect(...) <- Planning what to build
⎿ Done (3 tool uses · 25s) <- Phase complete, took 25 seconds
● nw-software-crafter(...) <- Writing and testing code
⎿ Done (10 tool uses · 1m) <- This is the longest phase
● nw-software-crafter-reviewer(...) <- Independent quality check
⎿ Done (8 tool uses · 42s)
\`\`\`
Messages You Can Safely Ignore
Internal coordination messages confuse new users. Provide an explicit safe-to-ignore list:
### Messages you can safely ignore
These lines appear during normal operation and are not errors:
- `PreToolUse:Task hook error` -- DES validation checkpoint
- `DES_MARKERS_MISSING` -- Internal formatting check, auto-retries
- `⎿ SubagentStop` -- Agent coordination signal
Think of these as the agent's internal quality gates. They ensure
every step follows the engineering protocol.
Success Verification
Replace exact-output matching with outcome-based verification:
Traditional tutorial (deterministic):
You should see:
\`\`\`
Hello, World!
\`\`\`
AI workflow tutorial (non-deterministic):
**Verify success:**
\`\`\`bash
pytest tests/ -v
\`\`\`
All tests should pass. The exact number of tests may vary (the agent
sometimes adds extra tests beyond your originals). What matters: zero
failures.
\`\`\`bash
ls src/auth/
\`\`\`
You should see at least: `__init__.py`, `handlers.py`, `models.py`.
File names may differ slightly. The agent chose names based on its
analysis of your requirements.
Progressive Trust Building
Structure AI workflow tutorials to build trust incrementally:
Level 1: Micro-success (Step 1-2)
- Trivially small task where AI succeeds visibly
- User can verify independently within 30 seconds
- Example: generate a single function from one test
Level 2: Small feature (Step 3-4)
- Multi-step task with checkpoint verification
- User starts to trust the process
- Example: implement a module with 3-5 tests
Level 3: Full workflow (Step 5+)
- Complete feature delivery end-to-end
- User understands how to verify and intervene
- Example: full TDD delivery with review and mutation testing
Handling Divergence
When user output differs from the tutorial:
### What if my output looks different?
The agent generates code based on your specific tests and context.
Common variations:
| Tutorial shows | You might see | Both are correct because |
|---------------|---------------|------------------------|
| `class AuthHandler` | `def handle_auth()` | Function vs class is a style choice; tests verify behavior |
| 3 implementation steps | 2 or 4 steps | Agent may split or combine based on complexity |
| `jwt.encode(...)` | `create_token(...)` | Naming varies; the test contract is what matters |
**The rule**: if `pytest tests/ -v` passes, the implementation is correct
regardless of how it differs from the examples.
Recovery Patterns
AI workflows can fail or produce unexpected results. Provide escape hatches:
> **If tests fail after delivery**: Run `/nw:deliver` again with the same
> description. The agent detects existing code and failing tests, then
> fixes them. This is a resume, not a restart.
> **If the agent seems confused**: Start fresh with `git stash` to save
> your current state, then `git checkout step-2` to reset to the last
> known-good checkpoint.
> **If you want to start over entirely**: `git checkout main` returns
> to the original starter state.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?