docs: record agent challenge skill bundle

skills/wf-cli/SKILL.md

@@ -53,6 +53,20 @@ wf run start <deployment_id> --input-file input.json
 wf run trace <run_id> --from 0 --limit 25
 ```
 
+## Public Discovery Order
+
+Use public CLI surfaces before broader documentation or implementation search:
+
+1. `wf status`
+2. `wf cap list --format ids`
+3. `wf cap inspect <capability>`
+4. `wf schema` to list workflow document/component shapes
+5. `wf schema draft`, `wf schema raw`, or `wf schema <Component>`
+6. `wf explain <diagnostic-code>` after validation failures
+
+Use `wf schema <name> --verbose` only when the complete JSON Schema is required;
+the default compact outline is preferred for agent context.
+
 ## Rules
 
 - Use explicit `--config <path>` for examples, challenge workspaces, and
@@ -74,3 +88,9 @@ wf run trace <run_id> --from 0 --limit 25
   JSON guidance before authoring.
 - Add `--verbose` only when a complete JSON Schema document is required; it may
   be large.
+- Prefer `wf schema` over searching tests or implementation code for draft/raw
+  plan shape.
+- Treat compact schema output as authoring guidance; use validation commands as
+  the source of truth for a concrete document.
+- If public commands and supplied skills are insufficient, report the exact
+  blocker instead of guessing undocumented fields.

skills/wf-workflow/SKILL.md

@@ -55,9 +55,17 @@ low-level escape hatch or you already have a complete compiler/generated plan.
 
 ## 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.
+Read only the reference needed for the current task:
+
+- Start with `system-model.md` when lifecycle vocabulary is unclear.
+- Use `workflow-lifecycle.md` for operation order.
+- Use `capabilities-and-wrappers.md` before selecting a source capability.
+- Use `draft-workspaces.md` for iterative editing.
+- Use `direct-plan-import.md` only when a complete raw plan is required.
+- Use `troubleshooting.md` after a public validation/run failure.
+
+Before authoring JSON, query the live public model with `wf schema`; the
+references explain semantics while the command reflects the current shape.
 
 Useful patterns:
 

skills/wf-workflow/references/troubleshooting.md

@@ -7,17 +7,16 @@ unrunnable, or surprising.
 
 Check in this order:
 
-1. `wf.admin.list_sources`
-2. `wf.admin.inspect_source`
-3. `wf.workflow.list_capabilities`
-4. `wf.workflow.inspect_capability`
+1. `wf status`
+2. `wf cap inspect <capability>`
+3. `wf cap list --format ids`
 
 Remember: MCP control tools are not workflow capabilities. They appear in
-MCP `tools/list`, not `wf.workflow.list_capabilities`.
+MCP `tools/list`, not `wf cap list`.
 
 ## Unrunnable Deployment
 
-Run `validate_deployment` before `run_deployment`.
+Run `wf deploy validate <deployment_id>` before `wf run start`.
 
 Common diagnostics:
 
@@ -27,16 +26,16 @@ Common diagnostics:
 - `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.
+Use `wf explain <diagnostic-code>` after validation failures to get
+human-readable explanations.
 
 ## 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.
+2. Use `wf run inspect <run_id>` for stored summary.
+3. Use `wf run trace <run_id> --from <n> --limit <n>` with a bounded range.
 
 Do not request full traces unless the user explicitly asks and the trace is
 known to be small.
@@ -44,5 +43,5 @@ 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`
+saved workflows becoming new tools. Use `wf run start` and `wf cap call`
 instead.