skills
This commit is contained in:
@@ -0,0 +1,52 @@
|
||||
# Capabilities And Wrappers Reference
|
||||
|
||||
Use this when deciding whether to call a capability directly, wrap it, or place
|
||||
it in a workflow.
|
||||
|
||||
## Core Split
|
||||
|
||||
```text
|
||||
raw MCP tool != workflow capability
|
||||
```
|
||||
|
||||
A raw MCP tool may be callable and still be awkward for workflows. Workflow
|
||||
capabilities are graph-facing contracts with schemas and outcomes.
|
||||
|
||||
## Discovery Order
|
||||
|
||||
1. Use `wf.admin.list_sources` to understand owners.
|
||||
2. Use `wf.workflow.list_capabilities` for graph-ready capabilities.
|
||||
3. Use `wf.workflow.inspect_capability` for one full contract.
|
||||
4. Use `wf.workflow.call_capability` to test a single workflow-facing contract.
|
||||
|
||||
## Wrapper Artifacts
|
||||
|
||||
Use a wrapper artifact when the raw provider shape needs normalization:
|
||||
|
||||
- provider status strings should become workflow outcomes
|
||||
- raw envelopes should be narrowed
|
||||
- `isError` or error blocks need explicit outcome routing
|
||||
- provider inputs are too broad or unstable for graph use
|
||||
|
||||
Saved wrappers appear as workflow capabilities under source id `workflow`, with
|
||||
names like `workflow.echo_wrapper.v1`.
|
||||
|
||||
## Wrapper Hints
|
||||
|
||||
`inspect_capability` returns `wrapper_hints`. Treat them as authoring
|
||||
scaffolding:
|
||||
|
||||
- `confidence=high`: simple shape, likely safe to validate first
|
||||
- `confidence=medium`: usable but review candidates
|
||||
- `confidence=low`: patch missing decisions before saving
|
||||
|
||||
`next_actions` is guidance, not validation authority.
|
||||
|
||||
## MCP Content Blocks
|
||||
|
||||
MCP tools often return `content: [{type, text, ...}]`. Do not map this list
|
||||
into a string state field. Filter/extract text explicitly, or write a wrapper
|
||||
that decides what content types are acceptable.
|
||||
|
||||
If a result exposes a convenience `text` field, inspect the capability schema
|
||||
and wrapper hints before using it. Do not assume every content block is text.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Draft Workspaces Reference
|
||||
|
||||
Use draft workspaces for iterative workflow authoring. They are mutable and
|
||||
revisioned; artifacts are immutable and versioned.
|
||||
|
||||
## Draft Shape
|
||||
|
||||
A draft has:
|
||||
|
||||
- `name`
|
||||
- `input_schema`
|
||||
- `state_schema`
|
||||
- `output_schema`
|
||||
- `start`
|
||||
- `steps`
|
||||
- `routes`
|
||||
- optional top-level `output`
|
||||
|
||||
`steps` are keyed by stable ids. `routes` map outcomes to another step id or
|
||||
`__end__`.
|
||||
|
||||
## Mapping Rules
|
||||
|
||||
Step input bindings read graph values into node-local input:
|
||||
|
||||
```json
|
||||
{
|
||||
"target": { "root": "local", "parts": ["text"] },
|
||||
"path": { "root": "input", "parts": ["text"] }
|
||||
}
|
||||
```
|
||||
|
||||
Step output bindings write node-local output into workflow state:
|
||||
|
||||
```json
|
||||
{
|
||||
"source": { "root": "local", "parts": ["echoed"] },
|
||||
"target": { "root": "state", "parts": ["echoed"] }
|
||||
}
|
||||
```
|
||||
|
||||
Top-level workflow output uses `path` / `target`, not step-level
|
||||
`source` / `target`:
|
||||
|
||||
```json
|
||||
{
|
||||
"path": { "root": "state", "parts": ["echoed"] },
|
||||
"target": { "root": "local", "parts": ["echoed"] }
|
||||
}
|
||||
```
|
||||
|
||||
## Workspace Flow
|
||||
|
||||
1. Create workspace from capability.
|
||||
2. Get workspace with `include_draft=true` before patching.
|
||||
3. Patch with current `revision`.
|
||||
4. Validate workspace.
|
||||
5. Save artifact or wrapper from workspace.
|
||||
|
||||
If a patch returns `revision_conflict`, fetch the workspace again and retry
|
||||
against the latest revision.
|
||||
|
||||
## Focused Helpers
|
||||
|
||||
Prefer focused helpers over JSON Patch for common edits:
|
||||
|
||||
- `set_draft_name`
|
||||
- `set_draft_route`
|
||||
- `set_step_input_map`
|
||||
- `set_step_output_map`
|
||||
|
||||
Use JSON Patch for structural edits the helpers do not cover.
|
||||
@@ -0,0 +1,48 @@
|
||||
# Workflow Troubleshooting Reference
|
||||
|
||||
Use this when a source, capability, artifact, deployment, or run is missing,
|
||||
unrunnable, or surprising.
|
||||
|
||||
## Missing Capability
|
||||
|
||||
Check in this order:
|
||||
|
||||
1. `wf.admin.list_sources`
|
||||
2. `wf.admin.inspect_source`
|
||||
3. `wf.workflow.list_capabilities`
|
||||
4. `wf.workflow.inspect_capability`
|
||||
|
||||
Remember: MCP control tools are not workflow capabilities. They appear in
|
||||
MCP `tools/list`, not `wf.workflow.list_capabilities`.
|
||||
|
||||
## Unrunnable Deployment
|
||||
|
||||
Run `validate_deployment` before `run_deployment`.
|
||||
|
||||
Common diagnostics:
|
||||
|
||||
- `binding_missing`: deployment lacks a logical-to-concrete source binding.
|
||||
- `source_missing`: bound concrete source does not exist or is disabled.
|
||||
- `capability_missing`: required node/reducer is not available.
|
||||
- `schema_changed`: saved snapshot no longer matches current source.
|
||||
- `source_unreachable`: live check could not contact an upstream source.
|
||||
|
||||
Use `live_check=true` only when you intentionally want to contact upstream
|
||||
sources. It may spawn stdio servers or perform network I/O.
|
||||
|
||||
## Run Debugging
|
||||
|
||||
If a run fails:
|
||||
|
||||
1. Read `status`, `error`, `diagnostics`, and `trace_count`.
|
||||
2. Use `inspect_run` for stored summary.
|
||||
3. Use `read_run_trace` with a bounded range.
|
||||
|
||||
Do not request full traces unless the user explicitly asks and the trace is
|
||||
known to be small.
|
||||
|
||||
## Harness Problems
|
||||
|
||||
Some LLM harnesses do not refresh `tools/list` mid-session. Do not rely on new
|
||||
saved workflows becoming new tools. Use `run_deployment` and `call_capability`
|
||||
instead.
|
||||
@@ -0,0 +1,48 @@
|
||||
# Workflow Lifecycle Reference
|
||||
|
||||
Use this when an agent needs to go from available capabilities to a saved,
|
||||
validated, runnable deployment.
|
||||
|
||||
## Primary Path
|
||||
|
||||
1. List sources.
|
||||
- MCP: `wf.admin.list_sources`
|
||||
- CLI: `wf cap list --format ids`
|
||||
2. List workflow capabilities.
|
||||
- MCP: `wf.workflow.list_capabilities`
|
||||
- CLI: `wf cap list`
|
||||
3. Inspect one capability.
|
||||
- MCP: `wf.workflow.inspect_capability`
|
||||
- CLI: `wf cap inspect <name>`
|
||||
4. Bootstrap a draft workspace.
|
||||
- MCP: `wf.workflow.create_draft_workspace_from_capability`
|
||||
- CLI: `wf draft create-from-capability <workspace_id> <capability>`
|
||||
5. Inspect/patch/validate the workspace until valid.
|
||||
- Prefer focused helpers when available.
|
||||
- Use JSON Patch only for general edits.
|
||||
6. Save an artifact.
|
||||
- Full workflow: `create_artifact_from_workspace`
|
||||
- Reusable wrapper: `create_wrapper_from_workspace`
|
||||
7. Save and validate a deployment.
|
||||
8. Run the deployment.
|
||||
9. Inspect the run summary first; read bounded traces only when needed.
|
||||
|
||||
## Object Model
|
||||
|
||||
- **Source**: owner of capabilities, such as `wf.std` or `everything.default`.
|
||||
- **Workflow capability**: graph-ready `NodeSpec` or saved wrapper artifact.
|
||||
- **Artifact**: immutable saved workflow or wrapper.
|
||||
- **Deployment**: mutable binding from artifact version to concrete sources.
|
||||
- **Run**: durable stopped execution record with status, output, and trace count.
|
||||
|
||||
## Result Handling
|
||||
|
||||
`run_deployment` returns compact status by default. Capture `run_id` even for
|
||||
completed or failed runs. Use:
|
||||
|
||||
- `inspect_run` for compact stored result.
|
||||
- `read_run_trace` for explicit debug slices, for example
|
||||
`{"start": 0, "limit": 25}`.
|
||||
- `resume_run` only for interrupted runs.
|
||||
|
||||
Do not ask for unbounded traces.
|
||||
Reference in New Issue
Block a user