skill-to-workflow

Skill to Workflow

Convert an Agent-oriented Skill into an implementable Workflow specification. The goal of the conversion is not to copy the numbering from the original text, but to restore its real execution graph and give every node clear responsibility, structured inputs and outputs, tool permissions, stop conditions, and failure handling.

Inputs and Default Deliverables

• The input can be a Skill directory,SKILL.md, Prompt, SOP, operating manual, or an Agent process described by the user.
• When the user specifies a target platform, use the nodes, variables, branches, and sub-workflow capabilities supported by that platform; when unspecified, output a platform-agnostic specification and do not guess specific implementations such as Dify, Coze, n8n, or LangGraph.
• When the user only asks for a summary, first give the number of stages, the main path, and key loops; when the user asks for design or conversion, then give the full node specifications.
• When implementation, file creation, or deployment is not explicitly requested, deliver only the design, do not modify the original Skill, and do not create platform configuration.

When a complete Workflow specification needs to be output, read references/workflow-spec-template.md。

Before Starting

1. Fully read the source Skill and the required references it declares; do not decompose based only on the surface-level numbering of SKILL.md .
2. Check the scripts, schemas, templates, validators, and official artifact paths used by the source Skill. Only read resources that would change the process design.
3. Distinguish three types of information:
   • business semantics and judgment rules;
   • execution mechanisms and tool operations;
   • output formats and acceptance constraints.
4. Record the original Skill's authorization boundaries, privacy boundaries, prohibitions, and inviolable sources of truth.
5. Do not execute the source Skill's business tasks unless the user also asks to run or verify the converted Workflow.

Conversion Process

1. Establish the Source Skill Contract

Extract:

• trigger conditions and out-of-scope cases;
• required inputs, optional inputs, and input selection rules;
• final artifacts and their consumers;
• sources of truth, data contracts, and quality thresholds;
• prohibited actions, permission restrictions, and human confirmation points;
• reusable historical artifacts and idempotency requirements.

These constraints must find a place in the Workflow and must not disappear because of node decomposition.

2. Restore the Real Execution Graph

Do not mechanically convert the original text's "seven steps" into seven nodes. First identify:

• batch-level steps and per-object loops;
• serial dependencies and tasks that can be parallelized;
• conditional branches, fallbacks, supplementary research, and retries;
• blocking failures, partial completion that is allowed to continue, and normal empty results;
• intermediate analysis states and formal deliverables.

Represent the real execution graph with one main path and necessary loops, then decide the number of nodes.

3. Divide Nodes

A node should complete one stable responsibility and produce a verifiable state change. Prioritize splitting when any of the following conditions is met:

• Different judgment bases, tool permissions, or failure strategies;
• The result needs to be cached, reused, manually checked, or retried separately;
• Downstream depends on only part of its output;
• Deterministic processing is mixed with model judgment;
• A single node simultaneously finds facts, makes business judgments, scores, and writes the final report.

Do not split purely mechanical format handling, thought fragments that cannot be independently validated, or tiny steps that only add context-passing overhead.

4. Classify nodes

Choose a primary execution type for each node:

• **Deterministic nodes:** parsing, cleaning, computation, field mapping, file generation, Schema validation; prefer code or platform-native nodes.
• **LLM judgment nodes:** classification, reasoning, extraction, trade-offs, and structured writing; input evidence and output Schema must be constrained.
• **Tool nodes:** search, web reading, database queries, API calls, or file parsing; grant only the tools this node needs.
• **Human nodes:** used when business authorization, subjective final decisions, or high-risk external changes are required.
• **Routing nodes:** choose the next step based on explicit state or rules, without undertaking additional business analysis.

Computation, assembly, and validation that can be reliably completed by deterministic logic should not be handed to the LLM.

5. Extract shared-capability sub-workflows

When two or more nodes repeatedly use the same external mechanism and a stable input-output contract can be formed, extract the mechanism into a shared sub-workflow. For example:

• Search planning → Web Search → URL deduplication → Web Open → evidence extraction;
• File parsing → format normalization → field quality check;
• Structured artifact assembly → build → formal validation;
• Notification sending, approval, or external system writes.

Analysis nodes only submit "what needs to be answered"; the shared sub-workflow is responsible for "how to call tools and return materials." What is shared is the acquisition or processing mechanism, not the business conclusions of different nodes.

A shared sub-workflow must at least define: request type, question or goal, known context, tool and source preferences, budget, stopping conditions, returned data, unresolved issues, constraints, cache key, and error states.

Do not force abstraction in the following cases:

• Only the tool name is the same, but the input semantics, permissions, or failure risks are completely different;
• Sharing would cause the sub-workflow to directly draw conclusions on behalf of business nodes;
• A one-off operation has no stable reuse value;
• The abstraction would hide human authorization or high-risk side effects.

6. Design state and data contracts

Prefer passing structured state; do not use natural language reports as interfaces between nodes. At least distinguish:

• Raw input;
• Normalized input;
• Source or evidence ledger;
• Intermediate judgments and confidence;
• Constraints and unresolved issues;
• Formal artifacts;
• Run status and errors.

The recommended base state is complete | partial | failed, but it should be supplemented according to business semantics with skipped、needs_human or other states. A normal empty result must not be misjudged as a failure.

Each node's output may contain only the data needed downstream. Workflow internal fields must be filtered before generating formal artifacts and must not pollute the original Skill's formal Schema.

7. Design prompts

Use a "shared constraints + node task" prompt structure:

• The shared System Prompt holds fact boundaries, source rules, prohibitions, and expression and structured output requirements;
• The node Prompt only states this node's goal, input variables, decision order, output fields, and stop conditions;
• Tool invocation policy is placed in tool nodes or shared sub-workflows, and is not maintained repeatedly by every business node;
• Output uses JSON Schema or platform structured output, and does not rely on the model voluntarily following a natural language format.

The prompt must specify: what is fact, what allows limited inference, how to handle insufficient evidence, what must not be added, and when to stop. Scoring nodes may only consume established evidence, and should not search again and introduce new facts.

8. Design branches, loops and failure handling

Each loop defines:

• trigger condition;
• which node to return to;
• which fields may be supplemented or modified;
• maximum count, time, or cost budget;
• after stopping, whether it is partial、failed or handoff to a human.

Distinguish:

• Technical failure: timeout, parsing failure, API error;
• Data failure: missing required fields, Schema invalid;
• Insufficient evidence: partial completion or handoff to a human is allowed;
• Business conflict: retain the conflict and lower confidence according to the rules;
• High-risk operations: request authorization before execution, and do not bypass approval with automatic retries.

9. Make generation and acceptance deterministic

If the source Skill already has a builder, validator, or single source of truth, the Workflow must continue to use it. Recommended structure:

中间分析状态
→ 标准事实源组装
→ Schema 校验
→ 确定性生成交付物
→ 正式校验器

When validation fails, prioritize correcting the standard source of truth and regenerating, and do not let the LLM directly modify multiple derived artifacts separately. When repair based on existing evidence is impossible, route back to the upstream node where the information is actually missing.

10. Deliver and perform a coverage check

The complete specification must at least state:

• the main path, number of nodes, and node graph;
• each node's goal, type, input, output, tools, prompt, and acceptance;
• shared sub-workflows and request/response contracts;
• state, cache, sources, branches, loops, and retries;
• formal artifacts, build method, and end-to-end completion conditions;
• a rule coverage table from the source Skill to the Workflow nodes.

Finally, check item by item the source Skill's required steps, core boundaries, and completion checks, ensuring that no rule exists only in the original text but is left unowned in the Workflow.

Key design principles

• The number of nodes is determined by stable responsibilities and state boundaries, not by the number of headings in the source document.
• Shared tool mechanisms can be abstracted, but business judgments must not be mixed because tools are reused.
• Searching, reading, and evidence extraction are responsible for providing materials; analysis nodes are responsible for forming domain conclusions.
• Establish facts and tasks first, then score or decide; do not let the model score by impression while searching.
• Intermediate state can be rich, but the formal data contract must remain clean and compatible.
• Observability is not an extra report: node status, sources, limits, retry reasons, and artifact paths should become part of the runtime state.
• Without user authorization, designing a Workflow is not equivalent to executing, deploying, or triggering external side effects.