Summary
PAI uses Workflows/ as the directory name for procedure files nested inside a skill (e.g. Packs/Research/src/Workflows/ExtensiveResearch.md). In the broader AI agent ecosystem — Anthropic's own taxonomy, LangChain/LangGraph, Microsoft Agent Framework, CrewAI, Mastra, Pydantic AI, Temporal — "workflow" has converged on a specific, load-bearing meaning: a code-driven orchestration with predetermined control flow, distinguished from "agents" (LLM-driven control flow).
PAI's nested files don't have that property. They're inert markdown procedures with no frontmatter, no harness registration, and no independent trigger mechanism — they're loaded only when the parent SKILL.md instructs the model to Read them. Calling them "workflows" creates real cognitive friction for users coming from other frameworks and for newcomers who encountered Anthropic's "Building Effective Agents" taxonomy first.
This issue proposes renaming Workflows/ → Procedures/ and opens discussion on whether the rename is worth the migration cost.
The naming collision
Anthropic's own definition ("Building Effective Agents", Dec 2024):
Workflows are systems where LLMs and tools are orchestrated through predefined code paths.
LangChain/LangGraph adopt this verbatim. Microsoft Agent Framework (GA Oct 2025), Mastra, CrewAI Flow, Pydantic AI, Inngest AgentKit, and Temporal all use "workflow" to mean a code-defined orchestration object with its own executor, separate from the LLM. MCP (spec 2025-11-25) deliberately defines no workflow primitive — orchestration is host-side.
By this consensus definition, a PAI Workflows/*.md file is not a workflow. It is a procedure or mode the skill keeps in a separate file for tidiness. The actual orchestration of PAI skills (when one exists) runs inside the LLM's tool-calling loop driven by SKILL.md prose — that is prompt-driven dispatch, the opposite of "predefined code paths."
Mechanical evidence: PAI "workflows" lack workflow-level status
In Claude Code, the harness discovers and registers skills via SKILL.md frontmatter (name, description). At session start the harness injects a Level-1 listing of all skills into the system prompt. Skills become callable via the Skill tool or /<name>.
PAI workflow files have:
- No YAML frontmatter
- No registration with the harness
- No appearance in the L1 listing
- No independent trigger phrase
- No
Skill tool entry
They are loaded only when the parent SKILL.md's routing table tells the LLM to Read a specific path. The mechanism is string match inside markdown prose. By every Claude Code primitive, they are sub-resources of a skill — closer in kind to Templates/, References/, or Scripts/ than to anything orchestration-flavored.
Proposed rename
Options, in order of preference:
Procedures/ — matches what they actually are; "procedure" is widely used for named multi-step processes inside a capability.Modes/ — accurate for skills like Research where the files represent quick/standard/extensive/deep modes of one capability.Routines/ — neutral, clearly sub-skill.- Keep
Workflows/ and add a doc-level disclaimer pointing to the industry-standard meaning. (Not preferred — preserves the friction.)
Migration considerations
The rename touches ~500 path references across Packs/, plus Releases/ snapshots, CreateSkill templates, and convention docs. Realistic path:
- Tag a major version (v5.x) for the rename
- Provide a deprecation shim or migration script for users with custom skills
- Update
CreateSkill templates and convention docs
- Leave
Releases/v2.x–v4.x snapshots untouched (historical)
Happy to draft the rename PR if there's agreement in principle.
Sources
Industry-standard "workflow" definition:
Skills as context-loading primitive (not orchestration):
MCP — no workflow primitive:
Repo precedent for naming changes:
Summary
PAI uses
Workflows/as the directory name for procedure files nested inside a skill (e.g.Packs/Research/src/Workflows/ExtensiveResearch.md). In the broader AI agent ecosystem — Anthropic's own taxonomy, LangChain/LangGraph, Microsoft Agent Framework, CrewAI, Mastra, Pydantic AI, Temporal — "workflow" has converged on a specific, load-bearing meaning: a code-driven orchestration with predetermined control flow, distinguished from "agents" (LLM-driven control flow).PAI's nested files don't have that property. They're inert markdown procedures with no frontmatter, no harness registration, and no independent trigger mechanism — they're loaded only when the parent
SKILL.mdinstructs the model toReadthem. Calling them "workflows" creates real cognitive friction for users coming from other frameworks and for newcomers who encountered Anthropic's "Building Effective Agents" taxonomy first.This issue proposes renaming
Workflows/→Procedures/and opens discussion on whether the rename is worth the migration cost.The naming collision
Anthropic's own definition ("Building Effective Agents", Dec 2024):
LangChain/LangGraph adopt this verbatim. Microsoft Agent Framework (GA Oct 2025), Mastra, CrewAI Flow, Pydantic AI, Inngest AgentKit, and Temporal all use "workflow" to mean a code-defined orchestration object with its own executor, separate from the LLM. MCP (spec 2025-11-25) deliberately defines no workflow primitive — orchestration is host-side.
By this consensus definition, a PAI
Workflows/*.mdfile is not a workflow. It is a procedure or mode the skill keeps in a separate file for tidiness. The actual orchestration of PAI skills (when one exists) runs inside the LLM's tool-calling loop driven bySKILL.mdprose — that is prompt-driven dispatch, the opposite of "predefined code paths."Mechanical evidence: PAI "workflows" lack workflow-level status
In Claude Code, the harness discovers and registers skills via
SKILL.mdfrontmatter (name,description). At session start the harness injects a Level-1 listing of all skills into the system prompt. Skills become callable via theSkilltool or/<name>.PAI workflow files have:
Skilltool entryThey are loaded only when the parent
SKILL.md's routing table tells the LLM toReada specific path. The mechanism is string match inside markdown prose. By every Claude Code primitive, they are sub-resources of a skill — closer in kind toTemplates/,References/, orScripts/than to anything orchestration-flavored.Proposed rename
Options, in order of preference:
Procedures/— matches what they actually are; "procedure" is widely used for named multi-step processes inside a capability.Modes/— accurate for skills like Research where the files represent quick/standard/extensive/deep modes of one capability.Routines/— neutral, clearly sub-skill.Workflows/and add a doc-level disclaimer pointing to the industry-standard meaning. (Not preferred — preserves the friction.)Migration considerations
The rename touches ~500 path references across
Packs/, plusReleases/snapshots,CreateSkilltemplates, and convention docs. Realistic path:CreateSkilltemplates and convention docsReleases/v2.x–v4.xsnapshots untouched (historical)Happy to draft the rename PR if there's agreement in principle.
Sources
Industry-standard "workflow" definition:
Skills as context-loading primitive (not orchestration):
MCP — no workflow primitive:
Repo precedent for naming changes: