Follow the create-stateful-skill workflow to scaffold an advanced agent skill with
L4 state management, lifecycle artifacts, and deterministic skill chaining.
[!IMPORTANT]
Stateful Skill vs. Guided Sub-Agent Boundary (2026+)
- Stateful Skill (
create-stateful-skill): Runs directly in the main conversation. Persists state
across separate turns via filesystem schemas (.agent/learning/, .agent/state/, or artifact frontmatter).
Best for: lifecycle state transitions (Draft → Review → Final), cyclical workflows, persistent configs, and chained skill steps.
- Guided Workflow Sub-Agent (
create-sub-agent): Runs in an isolated forked context (context: fork).
Best for: long multi-turn conversational interviews or setup wizards where intermediate chatter must not pollute the main session.
- Stateless Procedural Skill (
create-skill): Use when no cross-turn state, counters, or schemas are needed.
Inputs
$ARGUMENTS — optional skill name or use-case description. Omit to start with discovery.
Steps
- If
$ARGUMENTS provides a skill name or context, use it to seed discovery.
- Pre-Scaffold Qualification: Verify that the skill requires cross-turn state (if not, redirect to
create-skill).
- Follow the phased workflow:
- Identify required L4 patterns from
pattern-decision-matrix.md (artifact lifecycle, cyclical state propagation, persistent configuration, escalation taxonomy).
- Design the state schema (JSON/YAML in
.agent/state/ or artifact frontmatter metadata).
- Design skill chaining via standard Offer-Next-Steps blocks (linking to subsequent
/skill-name capabilities, not legacy flat commands).
- Scaffold the skill directory:
SKILL.md (< 100-500 lines), evals/evals.json, references/ (offloaded schemas & rules).
- Run
audit_skill.py to verify compliance.
- Report created skill path, state schema, and next-step execution sequence.
Output
Skill directory with SKILL.md implementing selected L4 patterns, explicit state schemas,
lifecycle artifact templates, and skill-chaining transitions.
Edge Cases
- If
$ARGUMENTS is empty: begin with discovery — identify which L4 patterns apply.
- If the use case is simple (no persistent state, no chaining): recommend
create-skill instead.
- If the workflow requires multi-turn human interview loops: recommend
create-sub-agent instead.
- If state mutations are high-risk: configure escalation taxonomy steps and human confirmation gates.
1---2name: create-stateful-skill3plugin: agent-scaffolders4description: >5 Scaffolds an advanced stateful agent skill with filesystem-native state schemas, lifecycle state6 machines, and skill chaining. NOT for simple stateless skills (use `create-skill`), NOT for7 isolated conversational wizards / persona swarms (use `create-sub-agent`), and NOT for GitHub8 Actions workflows (use `create-agentic-workflow`).9argument-hint: "[skill-name]"10allowed-tools: Bash, Read, Write11---1213Follow the `create-stateful-skill` workflow to scaffold an advanced agent skill with14L4 state management, lifecycle artifacts, and deterministic skill chaining.1516> [!IMPORTANT]17> **Stateful Skill vs. Guided Sub-Agent Boundary (2026+)**18> - **Stateful Skill (`create-stateful-skill`)**: Runs directly in the main conversation. Persists state19> across separate turns via filesystem schemas (`.agent/learning/`, `.agent/state/`, or artifact frontmatter).20> Best for: lifecycle state transitions (Draft → Review → Final), cyclical workflows, persistent configs, and chained skill steps.21> - **Guided Workflow Sub-Agent (`create-sub-agent`)**: Runs in an isolated forked context (`context: fork`).22> Best for: long multi-turn conversational interviews or setup wizards where intermediate chatter must not pollute the main session.23> - **Stateless Procedural Skill (`create-skill`)**: Use when no cross-turn state, counters, or schemas are needed.2425## Inputs2627- `$ARGUMENTS` — optional skill name or use-case description. Omit to start with discovery.2829## Steps30311. If `$ARGUMENTS` provides a skill name or context, use it to seed discovery.322. **Pre-Scaffold Qualification**: Verify that the skill requires cross-turn state (if not, redirect to `create-skill`).333. Follow the phased workflow:34 - Identify required L4 patterns from `pattern-decision-matrix.md` (artifact lifecycle, cyclical state propagation, persistent configuration, escalation taxonomy).35 - Design the state schema (JSON/YAML in `.agent/state/` or artifact frontmatter metadata).36 - Design skill chaining via standard Offer-Next-Steps blocks (linking to subsequent `/skill-name` capabilities, not legacy flat commands).37 - Scaffold the skill directory: `SKILL.md` (< 100-500 lines), `evals/evals.json`, `references/` (offloaded schemas & rules).384. Run `audit_skill.py` to verify compliance.395. Report created skill path, state schema, and next-step execution sequence.4041## Output4243Skill directory with `SKILL.md` implementing selected L4 patterns, explicit state schemas,44lifecycle artifact templates, and skill-chaining transitions.4546## Edge Cases4748- If `$ARGUMENTS` is empty: begin with discovery — identify which L4 patterns apply.49- If the use case is simple (no persistent state, no chaining): recommend `create-skill` instead.50- If the workflow requires multi-turn human interview loops: recommend `create-sub-agent` instead.51- If state mutations are high-risk: configure escalation taxonomy steps and human confirmation gates.
richfrem