workflow-schema-tuning

Tune workflow-schema.json to adjust how AI agents generate workflows in cc-wf-studio.

5.4k|571|Updated Nov 1, 2025
One-click install
npx skills add https://github.com/breaking-brake/cc-wf-studio --skill workflow-schema-tuning
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: workflow-schema-tuning
Source: https://github.com/breaking-brake/cc-wf-studio/tree/main/.claude/skills/workflow-schema-tuning
Command: npx skills add https://github.com/breaking-brake/cc-wf-studio --skill workflow-schema-tuning

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

AI agents generating workflows in cc-wf-studio sometimes pick the wrong node types or follow false constraints, and the root cause is usually biased text inside resources/workflow-schema.json rather than missing rules. This Skill guides you through diagnosing and fixing those biases by treating schema edits as prompt engineering, not type definitions.

Core Features & Use Cases

  • Bias auditing checklist: Walks a prioritized list of bias sources, from the AI editing skill template down to node descriptions, guidance fields, examples, and top-level constraints.
  • Minimal-edit philosophy: Enforces the principle of aligning direction rather than prescribing rules, preferring removal of biased text over adding new guidance sections.
  • Build pipeline integration: Covers regenerating the TOON schema with npm run generate:toon, validating with npm run check and npm run build, and testing via npm run debug.
  • Use Case: When the AI editor keeps choosing sub-agent nodes for simple tasks, use this Skill to locate the biased description in the schema, make a minimal contrastive fix, regenerate the TOON file, and verify the corrected generation behavior.

Quick Start

Ask the AI to audit resources/workflow-schema.json for bias causing the wrong node type to be selected, then apply a minimal fix and regenerate the TOON schema.

Frequently Asked Questions about workflow-schema-tuning

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix AI agents choosing the wrong node type in cc-wf-studio?

Audit the bias sources in priority order: the ai-editing-skill-template.md step 4 text, nodeTypes descriptions, aiGenerationGuidance fields, examples, and top-level constraints. Prefer removing biased text or fixing one description over adding new guidance sections.

How do I regenerate the TOON schema after editing workflow-schema.json?

Run npm run generate:toon to regenerate resources/workflow-schema.toon from the JSON source. The full npm run build also performs this automatically as its first step, and you can grep the TOON file to confirm the change took effect.

Is workflow-schema.json a runtime validator for generated workflows?

No, the schema is a specification delivered to the AI editor at runtime via the get_workflow_schema MCP tool, not a runtime validator. Whatever the schema says, the AI believes, so edits should be treated as prompt engineering rather than type definitions.

When should I add aiGenerationGuidance to a node type?

Only after a concrete failure where a minimal description fix is provably insufficient. Detailed when-to-use lists treat the AI as a rules engine, bloat tokens, and fail on unanticipated cases, so test the minimal change first.

Why should schema text avoid Claude-specific phrasing?

The framework is multi-agent, supporting Claude Code, Codex, and other agents, so schema text must be agent-agnostic. Use phrases like isolated AI agent session instead of isolated Claude session to keep the schema valid across all supported agents.