# Workflow Schema Tuning

Use when modifying `resources/workflow-schema.json` in cc-wf-studio to influence how AI...

- Repository: https://github.com/breaking-brake/cc-wf-studio (5444 stars)
- Category: Design
- License: see repository
- Last updated: 2026-10-07
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add breaking-brake/cc-wf-studio --skill workflow-schema-tuning -g -a claude-code -y`
Codex: `npx skills add breaking-brake/cc-wf-studio --skill workflow-schema-tuning -g -a codex -y`
Cursor: `npx skills add breaking-brake/cc-wf-studio --skill workflow-schema-tuning -g -a cursor -y`
Gemini CLI: `npx skills add breaking-brake/cc-wf-studio --skill workflow-schema-tuning -g -a gemini-cli -y`

## Description

Use when modifying `resources/workflow-schema.json` in cc-wf-studio to influence how AI agents generate workflows via the cc-workflow-ai-editor skill. Triggers include "AIが特定のノードタイプを選んでくれない", "ワークフロー生成のバイアスを調整したい", "スキーマの description を変えたい", "新しいノードタイプを追加したい", "嘘の制約がスキーマに混じっていないか確認したい". Covers what the schema actually does (instructions to AI, not runtime constraints), the design philosophy (align direction, do not prescribe rules), the build pipeline (.json → .toon auto-generated), and known bias sources to audit.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Workflow Schema Tuning

The schema (`resources/workflow-schema.json`) is the primary spec **delivered to the AI editor at runtime** via the `get_workflow_schema` MCP tool. It is not a runtime validator, the runtime barely validates anything. **Whatever the schema says, the AI believes.** Treat schema edits as prompt engineering, not type definitions.

## Core principle: align direction, do not prescribe rules

AI agents already know how to choose between node types intuitively (e.g., when to delegate to a sub-agent vs. handle in-context). The fix for bad output is almost never "add more rules", it is "remove what is biasing the AI in the wrong direction."

**Defaults**:
- Prefer minimal description text that states each node's *positional role* (立ち位置). Example: "A step executed by the main orchestrating agent" vs. "A step executed by an isolated sub-agent." The contrast does the work.
- Avoid `aiGenerationGuidance` lists of "when to use / when not to use / anti-patterns." They treat the AI as a rules engine, bloat tokens, and fail on unanticipated cases.
- **Test minimal first.** Only add guidance after a concrete failure where the minimal change is provably insufficient.

**Anti-pattern**: writing detailed `upgradeToSubAgentWhen` / `stayInPromptWhen` lists. If you find yourself writing 3+ bullets explaining when to use a node, the description itself is probably wrong.

## Schema architecture

| File | Role | Editable? |
|---|---|---|
| `resources/workflow-schema.json` | Single source of truth | YES |
| `resources/workflow-schema.toon` | Token-efficient format consumed by AI via MCP | NO, auto-generated |
| `resources/ai-editing-skill-template.md` | Skill template loaded at AI editor launch | YES |
| `scripts/generate-toon-schema.ts` | TOON generator | YES (rare) |

After editing `.json`, regenerate `.toon`:

```bash
npm run generate:toon
```

The full build (`npm run build`) does this automatically as the first step.

## Where biases hide (audit checklist)

The rest: https://github.com/breaking-brake/cc-wf-studio/blob/HEAD/.claude/skills/workflow-schema-tuning/SKILL.md