75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
---
|
|
name: wf-workflow
|
|
description: Use when an agent needs to discover workflow capabilities, create or patch draft workspaces, save workflow or wrapper artifacts, deploy, run, resume, debug, or troubleshoot workflows in this repository.
|
|
---
|
|
|
|
# wf Workflow
|
|
|
|
Use this skill for the workflow lifecycle, regardless of front door:
|
|
|
|
- MCP tools exposed by `wf.workflow.*`
|
|
- repo-local `wf` CLI commands
|
|
- future `wf_api` callers
|
|
|
|
Prefer small discovery calls, draft workspaces, validation, and bounded trace
|
|
reads. Do not write raw workflow plans unless the user explicitly asks for the
|
|
low-level escape hatch.
|
|
|
|
## Workflow Lifecycle
|
|
|
|
1. Discover sources with `wf.admin.list_sources` or `wf cap list`.
|
|
2. Discover workflow-ready capabilities with `wf.workflow.list_capabilities`.
|
|
3. Inspect one candidate with `wf.workflow.inspect_capability`.
|
|
4. Call one candidate with `wf.workflow.call_capability` or `wf cap call` when
|
|
payload shape or upstream source reachability is uncertain.
|
|
5. Create a patchable draft workspace with
|
|
`wf.workflow.create_draft_workspace_from_capability`.
|
|
6. Patch targeted fields with focused helpers or JSON Patch.
|
|
7. Validate with `wf.workflow.validate_draft_workspace`.
|
|
8. Save with `wf.workflow.create_artifact_from_workspace` or
|
|
`wf.workflow.create_wrapper_from_workspace`.
|
|
9. Save a deployment with `wf.workflow.save_deployment`.
|
|
10. Validate with `wf.workflow.validate_deployment`.
|
|
11. Run with `wf.workflow.run_deployment`.
|
|
12. Inspect stopped runs with `wf.workflow.inspect_run`; read bounded trace
|
|
slices only when debugging.
|
|
|
|
## Rules
|
|
|
|
- Use workflow capabilities, not raw MCP tools, when building graphs.
|
|
- Use `call_capability` for single-call probes; use deployments/runs for durable
|
|
lifecycle behavior.
|
|
- Treat wrapper hints as scaffolding, not semantic truth.
|
|
- Use draft workspaces for iterative authoring; avoid rewriting full drafts.
|
|
- Use explicit source bindings at deployment time.
|
|
- Keep traces bounded with `trace_range`.
|
|
- Do not expect a newly saved workflow to become a new MCP tool mid-session.
|
|
- For MCP content blocks, add explicit extraction/wrapper steps instead of
|
|
pretending `content` is always plain text.
|
|
|
|
## References
|
|
|
|
Read only the reference needed for the current task. Start with a small preview
|
|
or search hit, then open the relevant section; do not dump every reference into
|
|
context.
|
|
|
|
Useful patterns:
|
|
|
|
```bash
|
|
# PowerShell preview
|
|
Get-Content skills/wf-workflow/references/workflow-lifecycle.md -TotalCount 40
|
|
|
|
# Targeted search
|
|
rg -n "trace|resume|binding_missing|wrapper_hints" skills/wf-workflow/references
|
|
```
|
|
|
|
- `references/workflow-lifecycle.md`: end-to-end lifecycle and tool order.
|
|
- `references/capabilities-and-wrappers.md`: raw capability vs workflow
|
|
capability, wrapper artifacts, and content-block handling.
|
|
- `references/draft-workspaces.md`: draft shape, mappings, patches, and save
|
|
path.
|
|
- `references/troubleshooting.md`: missing source/capability, unrunnable
|
|
deployment, run/trace issues.
|
|
|
|
For shell-first workflows, also use the existing `wf-cli` skill.
|