<div align="center"> <img src="./skills/reasoning-workflow/assets/icon.svg" width="88" height="88" alt="Reasoning Workflow" />

Reasoning Workflow

Understand the problem before you search, decide, or act

A general-purpose governing Skill for reasoning, Deep Research, decisions, controlled execution, verification, and evidence-gated workflow learning.

English · 简体中文

Start in 30 seconds · Choose an edition · How to use it · Depth · Architecture · Repository

Browse Portable / canonical Skill · Browse Modular edition · Read SKILL.md

</div>

---

Why this exists

Powerful agents can search, write, code, call tools, delegate work, and operate for a long time. The hard part is increasingly not whether an agent can do something, but whether it is solving the right problem, using the right evidence, allocating enough—but not excessive—effort, preserving state correctly, and knowing when a result is actually complete.

Reasoning Workflow governs that layer.

It helps an agent answer questions such as:

• What is the real task or desired outcome?
• Is the problem well framed, or is the current framing itself uncertain?
• Which premise, causal edge, constraint, or missing observation actually carries the answer?
• Should the next move be reasoning, retrieval, a calculation, a specialist Skill, a user question, a worker, or no further work at all?
• What evidence would distinguish competing explanations?
• Is a recommendation robust, or does it flip under a small change in assumptions or user preferences?
• Is a failed action a local tool error, a planning failure, an observation failure, or evidence that the whole frame changed?
• Does a second reviewer provide genuinely independent verification, or merely repeat the same failure mode?
• What must be true before the task can be closed?

The goal is not to make every task longer. The goal is to make effort proportional to uncertainty, consequence, and actual decision value.

Research follows the structure of the problem, not merely the wording of the prompt.

---

What it is — and what it is not

Reasoning Workflow is a governing Skill above specialist capabilities. It can coordinate a coding Skill, browser, data-analysis Skill, design Skill, local tools, connectors, subagents, or other domain methods without trying to replace them.

It is not:

• a prompt collection;
• a fixed chain-of-thought template;
• a mandatory long checklist;
• a “search N sources” recipe;
• a fixed multi-agent hierarchy;
• a reason to ask the user more questions than necessary;
• a replacement for permissions, safety controls, domain expertise, or specialist Skills;
• proof that an answer is correct merely because the workflow was invoked.

The design favors semantic invariants + adaptive strategy. Strong models should have room to choose, reorder, repeat, compress, or skip strategies when the current task state justifies it.

---

Start in 30 seconds

One command for supported coding agents

If you use the open skills CLI, the fastest cross-agent install is:

npx skills add zy839971925-zyy/Agent--deep-research-Workflow-Skills --skill reasoning-workflow

The CLI can target supported agents such as Codex and Claude Code. Add -g for a user-wide install, or use --list first to inspect the Skills exposed by this repository.

# Inspect before installing
npx skills add zy839971925-zyy/Agent--deep-research-Workflow-Skills --list

# Example: install Portable globally for Codex
npx skills add zy839971925-zyy/Agent--deep-research-Workflow-Skills \
  --skill reasoning-workflow --agent codex -g

This is a community/open-ecosystem installer, not a requirement. Manual and host-native installation remain supported below.

ChatGPT Skills

If your ChatGPT workspace supports uploaded Skills:

1. Open Plugins → Skills.
2. Choose Create → Upload from your computer.
3. Upload the Portable Skill folder/package built from skills/reasoning-workflow/.
4. After installation, ask ChatGPT to use Reasoning Workflow on a task.

If you package the folder yourself, keep SKILL.md at the root of the uploaded Skill package together with its references/, families/, schemas/, scripts/, agents/, and assets/ directories.

Codex

The Portable edition follows the Agent Skills structure. A direct GitHub-folder install can be requested with Codex's skill installer:

$skill-installer install https://github.com/zy839971925-zyy/Agent--deep-research-Workflow-Skills/tree/main/skills/reasoning-workflow

Or copy the folder into a standard Codex/Agent Skills location such as:

.agents/skills/reasoning-workflow/

This repository also includes .codex-plugin/plugin.json for plugin-style discovery.

Claude Code

Copy the Portable Skill folder to either a project-level or user-level Skills directory:

# Project
.claude/skills/reasoning-workflow/

# User-wide
~/.claude/skills/reasoning-workflow/

The named directory should contain SKILL.md; do not place SKILL.md loose directly under skills/.

Other Agent Skills-compatible clients

Use the same self-contained folder:

skills/reasoning-workflow/
└── SKILL.md

The public Agent Skills specification defines SKILL.md as the required entry point and allows optional scripts, references, and assets. Host-specific discovery locations vary, so use the directory that your client documents.

---

Choose an edition

The repository exposes both editions as normal folders. There are no opaque distribution ZIPs in main, so GitHub users can inspect everything before installing it.

| Edition | Location | Best for | Runtime model | | --- | --- | --- | --- | | Portable / canonical | skills/reasoning-workflow/ | Most users; ChatGPT/Codex/Claude; one governing Skill | Full depth gate, cross-Family routing, schemas and optional deterministic helpers | | Modular | modular/skills/ | Advanced hosts that compose several independent Skills | Six lightweight semantic Skills; no duplicated Python/schema runtime |

Portable is the default

Portable is the full governing workflow. It contains:

• SKILL.md — universal entry point;
• six Family indexes;
• progressively loaded references;
• machine-readable schemas for task/state/runtime contracts;
• a small set of runtime Python helpers for deterministic routing and validation;
• host metadata and the project icon.

It intentionally does not contain development-only tests, eval fixtures, build reports, generated distributions, or internal engineering artifacts.

Modular is intentionally lighter

The Modular edition exposes six independent semantic Skills without duplicating Portable's schemas or Python runtime into every Family:

• reasoning-core
• deep-research
• decision-analysis
• execution-control
• audit-verification
• workflow-learning

Each contains only its own instructions and Family references. If you need Reasoning Workflow's bundled deterministic router, semantic state validators, or full cross-Family governing loop, install Portable instead.

You can also install only the Modular capability you want with the skills CLI:

npx skills add zy839971925-zyy/Agent--deep-research-Workflow-Skills --skill deep-research
npx skills add zy839971925-zyy/Agent--deep-research-Workflow-Skills --skill decision-analysis

---

How to use it

You normally do not need a giant prompt. Give the agent the real goal, important constraints, and any depth preference that matters.

General use

Use Reasoning Workflow for this task.

Goal: [what I actually need]
Constraints: [scope, deadline, permissions, sources, risk boundaries]
Deliverable: [answer, recommendation, code change, report, artifact, etc.]

Choose proportionate depth. Do not turn a simple task into a project.

Deep Research

Use Reasoning Workflow at Deep depth to investigate this question: [question].

Build the research around the decisive premises, relationships, and causal links rather than literal keywords.
Distinguish frame uncertainty from answer uncertainty.
Prefer evidence routes that could actually change the answer.
Keep competing explanations alive until evidence discriminates between them.
Give me the best-supported conclusion, boundary conditions, and remaining material uncertainty.

Ultra Research

Use Reasoning Workflow at Ultra depth for: [question].

Spend the extra budget broadly before converging:
reframe the problem when useful, search for hidden relationships and omitted variables,
explore materially different hypotheses and evidence ecosystems,
and reset the research path if it becomes homogeneous or anchored.

Do not spend most of the extra budget repeatedly verifying the same claim.
Verify the pivotal claims strongly, then give me the calibrated answer and what could still change it.

Decision / recommendation

Use Reasoning Workflow to decide what I should do.

Goal: [goal]
Known options: [A, B, ...]
Constraints: [constraints]
Preferences: [what I care about, if known]

Check whether the option set is incomplete.
Separate factual uncertainty from model, preference, and option uncertainty.
Show the decisive trade-offs, robustness region, and conditions that would switch the recommendation.
Only ask me a question if the answer could materially improve the decision.

Causal or systems analysis

Use Reasoning Workflow to explain why [outcome] is happening.

Do not jump from sequence or correlation to causation.
Model only relationships that could materially change the explanation:
upstream causes, mediators, feedback, incentives, substitutes, delays,
confounders, reverse causality, thresholds, and competing mechanisms.

Controlled execution

Use Reasoning Workflow to implement [change].

Authorized scope: [scope]
Preserve: [invariants]
Do not change: [forbidden areas]

Use delegation only when a real bottleneck benefits from it.
Keep evidence-bearing handoffs compact.
Diagnose failures before replanning.
Verify the final effective state, not just the last successful tool call.

Keep it light

Use Reasoning Workflow, but keep this Light unless the task reveals a material hidden complication.

Reasoning Workflow may de-escalate as well as escalate. Invoking the workflow does not mean invoking Ultra.

---

Depth: Light to Ultra

Depth controls epistemic ambition and total budget, not a fixed number of searches, agents, steps, references, or model tokens.

| Depth | Best for | Typical behavior | | --- | --- | --- | | Light | Stable, direct, well-specified work | Minimal framing, direct answer/action, relevant check only | | Standard | Bounded analysis, writing, implementation | Normal reasoning and verification; limited supporting context | | Deep | Material uncertainty, causal questions, contested evidence | Explicit problem model, competing explanations, stronger evidence and challenge | | Max | Maximum useful depth within the current trajectory | Push the current framing/research path to its useful limit; strong material verification | | Ultra | Problems where the trajectory itself may be narrow, path-dependent, incomplete, or structurally uncertain | Much larger budget for reframing,