Waza: The 8 AI Skills That Fix Broken Agent Workflows

Your AI agent just shipped broken code to production. Again. It hallucinated a file path, skipped the tests, and summarized its own failure with cheerful confidence. You've burned three hours cleaning up a mess that should never have happened—and you're starting to wonder if these "coding agents" are more trouble than they're worth.

Here's the uncomfortable truth: the problem isn't the model. It's you.

Not your intelligence. Your structure. Raw AI capability without disciplined engineering habits drifts into chaos—generic output, missed edge cases, and that maddening tendency to act before understanding. What if you could transplant the precise rituals of senior engineers directly into your agent's runtime? Not as bloated frameworks or rigid rules that become ceilings, but as lean, battle-tested skills that set clear goals then get out of the way.

Enter Waza (技)—the open-source skill system that transforms how Claude Code and Codex operate. Born from 500+ hours of real project torture across 7 codebases, Waza distills eight engineering habits into slash commands your agent can actually execute. No more hoping your AI "gets it." No more reviewing diffs that rewrite working code into broken abstractions. Just precision, when you need it, where you need it.

In this deep dive, I'll expose exactly how Waza works, why top engineers are quietly adopting it, and how to install these eight skills in under 60 seconds. The repository lives at https://github.com/tw93/Waza—but don't click yet. What you're about to learn will change how you think about AI-assisted development forever.

What Is Waza? The Martial Arts Philosophy Behind Precision AI

Waza (技, pronounced "wah-zah") is a Japanese martial arts term for technique—a move practiced until it becomes instinct. That's not marketing fluff. It's the core philosophy driving every design decision in this project.

Created by Tw93, a seasoned engineer with deep roots in the Chinese developer community, Waza belongs to a deliberate trilogy: Kaku (書く) writes code, Waza (技) drills habits, and Kami (紙) ships documents. Think of them as a family unit—Kaku the dad handling generation, Waza the big sister enforcing discipline, Kami the little sister managing documentation.

But why now? Why does Waza matter in March 2025?

The AI coding agent landscape has exploded, but a critical gap has emerged. Tools like Superpowers and gstack impress with feature breadth, yet collapse under their own weight—too many skills, too much configuration, too steep a learning curve. Meanwhile, every rigid rule authors write becomes a ceiling: the model can only do what instructions explicitly permit, unable to adapt as capabilities evolve.

Waza inverts this. Each skill defines a clear goal and the constraints that actually matter, then steps back. The model operates within guardrails, not cages. As models improve, this restraint pays compound interest—skills become more valuable, not obsolete.

The /health skill particularly exemplifies this evolution. What began as a six-layer Claude Code configuration audit framework (detailed in Tw93's foundational post) now extends across Codex, verifier surfaces, and AI maintainability signals. It defaults to summary mode, only deepening inspection when you explicitly request a full audit or when initial classification fails. Budget-aware, context-sensitive, deliberately restrained.

The 8 Skills That Separate Amateur Agents from Precision Instruments

Waza ships eight skills, each mapping to a non-negotiable engineering habit. Here's the complete arsenal:

Each skill is a self-contained folder with reference docs, helper scripts, and gotchas from real failures. That last part matters enormously—every warning traces to actual pain: a wrong code path requiring four rounds to find, a release posted before artifacts uploaded, a server restarted eight times without reading the error log.

The /check skill exemplifies Waza's project-awareness. It doesn't just run generic linting—it reads your repository's public context from READMEs, package manifests, Makefiles, CI workflows, and explicit instructions. It knows your generated artifacts, protected files, version synchronization requirements. It becomes your codebase's institutional memory.

Real-World Scenarios Where Waza Transforms Chaos into Flow

Scenario 1: The Production Incident at 3 AM

Your pager screams. A feature that worked yesterday now 500s on every request. Without Waza, you frantically prompt Claude Code with "fix the bug" and watch it shotgun solutions—restarting services, tweaking configs, generating plausible-sounding explanations that don't match the logs.

With Waza: You invoke /hunt. The skill enforces systematic debugging: reproduce the issue, examine recent changes, confirm root cause before any fix. No more "try this, try that" roulette. The agent documents its reasoning chain, and you approve the actual fix with confidence.

Scenario 2: The "Quick" Feature That Became a Rewrite

Product wants "just a small dashboard widget." You prompt for implementation. The agent generates 400 lines of generic Tailwind, misses your design system's spacing tokens, and produces something that technically works but looks alien in your app.

With Waza: /think first challenges whether this should even be a new component versus extending existing patterns. /design then produces distinctive UI with screenshot-driven iteration—committed aesthetic direction, not defaults. The result fits your product like it grew there.

Scenario 3: The Documentation Debt Spiral

Your team ships fast, docs rot. New hires struggle with tribal knowledge. You know you should document, but writing feels like pulling teeth—especially in your second language.

With Waza: /learn runs six-phase research on your domain. /read fetches and cleans source material from scattered URLs and PDFs. /write polishes prose to sound natural in both Chinese and English, cutting the stiff formulaic phrasing that screams "translated by AI." You publish, not perfect, but genuinely useful.

Scenario 4: The Pre-Release Panic

It's Friday 4 PM. You need to ship. The agent says "done" but your gut churns. Did it run tests? Update versions? Handle the asset upload sequence correctly? You manually verify everything, find three issues, miss one that breaks production.

With Waza: /check reviews the diff against project-specific constraints, handles approved release/publish/push/reaction follow-through, and verifies with evidence. It knows your release ritual because you taught it once, and it never forgets.

Installation: From Zero to Precision in 60 Seconds

Waza installs globally so skills follow you across every project. Choose your weapon:

Claude Code (Recommended)

# Install complete skill bundle
npx skills add tw93/Waza -a claude-code -g -y

This registers all eight skills: /think, /design, /check, /hunt, /write, /learn, /read, and /health.

Install selectively:

# Just the debugging discipline you desperately need
npx skills add tw93/Waza --skill hunt -a claude-code -g -y

Claude Code plugin marketplace (alternative path):

/plugin marketplace add tw93/Waza
/plugin install waza@waza

⚠️ Known issue: Per-skill marketplace entries like waza-think@waza are temporarily affected by a Claude Code v2.1.136+ path-validation regression. Until upstream fixes this, use the npx skills add ... --skill path for individual skills.

Codex

# Full bundle
npx skills add tw93/Waza -a codex -g -y

# Single skill
npx skills add tw93/Waza --skill think -a codex -g -y

Codex sessions invoke installed skills by name or link directly to the installed SKILL.md path:

# Find where skills live
npx skills path tw93/Waza

Claude Desktop

Download waza.zip, then:

Customize > Skills > "+" > Create skill > Upload ZIP

Keeping Current

# Global update
npx skills update -g -y

# Marketplace installs
claude plugin update <skill>

# Claude Desktop: replace with latest waza.zip

Clean Removal

npx skills remove tw93/Waza -g

# Remove extras
rm -f ~/.claude/statusline.sh
rm -f ~/.claude/rules/english.md
rm -f ~/.claude/rules/anti-patterns.md

For Codex rule installs, remove the marked Waza block from ~/.codex/AGENTS.md.

Real Code: Inside Waza's Implementation

Let's examine actual patterns from the repository, starting with the installation infrastructure that makes global skill distribution possible.

Installation Command Architecture

The core installation leverages the skills CLI with provider-specific adapters:

# Complete bundle with all defaults accepted
npx skills add tw93/Waza -a claude-code -g -y

Breaking this down: npx executes without global installation, -a claude-code specifies the agent adapter, -g installs globally (available across all projects), -y auto-accepts prompts. The --skill flag filters to individual skills when you want surgical precision rather than the full arsenal.

Statusline Monitoring for Context Awareness

Waza includes a minimal statusline preventing the classic agent failure mode: context window exhaustion mid-task. For Claude Code:

# One-line installation
curl -sL https://raw.githubusercontent.com/tw93/Waza/main/scripts/setup-statusline.sh | bash

This produces context window monitoring with color-coded thresholds: green below 70%, yellow at 70-85%, red above 85%. Plus quota tracking for 5-hour and 7-day limits. No progress bar noise—just signal.

Codex users get native statusline items via config:

# ~/.codex/config.toml
[tui]
status_line = ["model-with-reasoning", "current-dir", "context-used", "five-hour-limit", "weekly-limit"]
status_line_use_colors = true

Critical difference: Codex shows remaining quota; the Claude Code statusline shows used percentage. Upstream doesn't yet offer five-hour-used / weekly-used items, so Waza fills the gap with its custom implementation.

Anti-Pattern Guardrails

Optional but powerful—always-on behavioral constraints that apply across every session:

# Install for Claude Code
curl -sL https://raw.githubusercontent.com/tw93/Waza/main/scripts/setup-anti-patterns.sh | bash -s -- claude-code

# Install for Codex
curl -sL https://raw.githubusercontent.com/tw93/Waza/main/scripts/setup-anti-patterns.sh | bash -s -- codex

These enforce four cross-skill rules: stop acting before reading, no hallucinated paths, no scope creep, no unsolicited summaries. Skill-agnostic, session-persistent, brutally effective.

English Coaching Integration

A delightful optional feature for multilingual teams. When prompts contain English mistakes, the agent appends a short 😇 correction; Chinese-only prompts stay untouched:

# Claude Code setup
curl -sL https://raw.githubusercontent.com/tw93/Waza/main/scripts/setup-english-coaching.sh | bash -s -- claude-code

# Codex setup  
curl -sL https://raw.githubusercontent.com/tw93/Waza/main/scripts/setup-english-coaching.sh | bash -s -- codex

This respects language context—no pedantic corrections when you're intentionally writing Chinese. The 😇 emoji signals coaching mode, keeping interactions light.

The /health Skill: Six-Layer Audit in Action

The crown jewel. /health evolved from a manual six-layer Claude Code framework into automated Agent Health scanning. It understands:

• AGENTS.md and CLAUDE.md project instructions
• Copilot/Gemini instruction files
• Codex configuration summaries
• Claude hooks and MCP when present
• Verifier logs
• AI maintainability signals

Default behavior is summary mode—fast, budget-aware classification. Only deepens to full inspection when you explicitly request deep or full audit, or when summary classification fails.

# Typical invocation flow (conceptual)
/health          # Summary pass, classify risk
/health deep     # Full inspection when needed

This design embodies Waza's core principle: restraint pays compound interest. Don't burn tokens on exhaustive audits when a glance suffices. Don't miss critical issues when classification fails.

Advanced Patterns: Chaining, Context, and Optimization

Waza skills are deliberately manual at transitions. Each completes its task and stops, waiting for your decision. This prevents the terrifying "agent goes rogue" scenario where one triggered skill cascades into uncontrolled action.

Proven workflow chains:

Each arrow is your explicit approval. The agent never decides to proceed autonomously.

Context optimization: /check becomes project-aware by reading repository context—README files, package manifests, Makefiles, CI workflows. It extracts commands, respects hard stops (generated artifacts, protected files, version sync requirements), and never leaks credentials. The template lives at skills/check/references/project-context.md.

Token budget discipline: The statusline prevents the silent killer of agent sessions—context window exhaustion. When you hit yellow (70-85%), wrap up current task. Red (85%+) means immediate checkpoint and restart. This sounds basic until you've lost 30 minutes of reasoning chain to a truncated context window.

Waza vs. The Competition: Why Restraint Wins

The pattern is clear: Waza trades breadth for depth, automation for control, feature count for reliability. Superpowers impresses in demos; Waza delivers at 3 AM when production is down.

Frequently Asked Questions

Q: Can I use Waza with Claude Desktop or only Claude Code?

A: All three platforms supported: Claude Code, Codex, and Claude Desktop. Desktop uses ZIP upload rather than CLI installation.

Q: Do skills auto-update when Waza releases improvements?

A: No—run npx skills update -g -y or claude plugin update <skill> periodically. The manual step prevents surprise behavior changes mid-project.

Q: Will Waza work with my custom project structure?

A: /check reads your actual repository context (READMEs, manifests, Makefiles) rather than assuming conventions. The more you document your project, the smarter Waza becomes.

Q: Can I contribute new skills?

A: Absolutely. The repository welcomes PRs. Every gotcha in existing skills traces to real failure—bring yours.

Q: Is Waza only for JavaScript/TypeScript projects?

A: No. Skills are language-agnostic. /hunt debugs Python equally well. /design targets frontend regardless of framework. /check adapts to any project's tooling.

Q: What happens when models improve—do skills become obsolete?

A: The opposite. Waza's restraint-based design means better models do more within the same constraints. Skills become more valuable, not less.

Q: How does /health differ from generic linter setups?

A: It audits agent configuration health—instruction files, hooks, MCP integrations, verifier outputs—not code style. It answers "is my agent setup correct?" not "is my code pretty?"

The Verdict: Why Waza Belongs in Your Toolkit

I've watched AI coding tools evolve from novelty to necessity to liability. The teams winning with agents aren't those with the fanciest prompts or the most plugins. They're the ones who impose discipline on capability.

Waza embodies this discipline. Eight skills, each honed through real failure, each respecting your judgment at transition points, each designed to improve as models improve. The martial arts metaphor holds: technique practiced until instinctive, then applied with precision under pressure.

The /health skill alone justifies adoption. That six-layer audit framework—born from actual Claude Code configuration disasters, now extended across Codex and verifier surfaces—catches the misconfigurations that silently sabotage agent performance. The summary-first, deep-when-needed approach respects your token budget while protecting against blind spots.

But Waza's deeper value is philosophical. In a landscape of ever-expanding agent capabilities, Tw93 chose restraint. Fewer skills, clearer triggers, manual transitions, documented gotchas. This isn't minimalism for aesthetics. It's operational sanity.

Install it. Chain /think into /design into /check. Feel the difference when your agent stops guessing and starts executing with purpose. When your 3 AM incidents get /hunted systematically instead of patched desperately. When your releases pass /check verification with confidence, not hope.

The repository awaits at https://github.com/tw93/Waza. Give it a star if it transforms your workflow. Open an issue when you find the next gotcha that should be documented. And if Waza delights your life, Tw93's cats TangYuan and Coke accept canned food donations—because even precision engineering tools deserve a little warmth.

Stop letting your agents drift. Give them Waza.