bf-skillsruntime-dev

Skills Runtime SDK Business Development Guide

Core principles:

• Offline-first: first get FakeChatBackend running through the minimal closed loop, then connect to a real model
• Skills-First: role capabilities should first be consolidated into SKILL.md, and the orchestration layer is only responsible for composition
• Evidence-first: side effects must be replayable in WAL / approvals / tool events
• Dual-track collaboration: use Coordinatorfor fixed roles, and collab primitives for dynamic subtasks

Fact snapshot:

• The current skill is verified against 2026-04-02 / SDK 0.1.11 Proofreading
• This skill only references references/ and scripts/
• within the current directory. If you find that the repository facts have changed again, first update this skill's local references, then continue using it

Opening actions

1. First locate the local repository root directory; do not default to cloning over the network.
2. First confirm whether the current environment already has skills-runtime-sdkinstalled; if not installed, then use the local repository for an editable install.
3. First choose the development form, then decide which local reference to read:
   • Single agent + tools: see references/recipes-index.md
   • Skills injection / references / actions: see references/config-templates.md
   • Multi-agent / dynamic collaboration: see references/api-cheatsheet.md + references/recipes-index.md
   • Security / approvals / sandbox: see references/safety-and-sandbox.md
   • Regression / verification / evidence: see references/testing-strategy.md

Local environment preparation

If the repository root directory is known, record it as REPO_ROOT：

export REPO_ROOT=/abs/path/to/skills-runtime-sdk

Choose one of two ways to install the SDK:

# 方式 A：开发模式安装（推荐）
pip install -e "$REPO_ROOT/packages/skills-runtime-sdk-python"

# 方式 B：临时 PYTHONPATH（不安装）
export PYTHONPATH="$REPO_ROOT/packages/skills-runtime-sdk-python/src"

Both CLI entry points are available:

skills-runtime-sdk --help
python3 -m skills_runtime.cli.main --help

Quick start

1) Generate the business skeleton

python3 scripts/scaffold_app.py my-app --out . --with-skills
# 预览：加 --dry-run
# 覆盖：加 --force

Generated by default:

• run.py
• config/runtime.yaml
• skills/
• tests/

2) Run offline

python3 run.py --workspace-root /tmp/my-app --mode offline

3) Minimal regression

pytest -q tests

If you are developing inside this repository, also run the repository gate:

bash scripts/pytest.sh
pytest -q packages/skills-runtime-sdk-python/tests/test_examples_smoke.py

Recommended imports and runnable skeleton

Minimal Agent

from pathlib import Path
from skills_runtime.agent import Agent
from skills_runtime.llm.fake import FakeChatBackend, FakeChatCall
from skills_runtime.llm.chat_sse import ChatStreamEvent

agent = Agent(
    workspace_root=Path("/tmp/demo").resolve(),
    backend=FakeChatBackend(calls=[
        FakeChatCall(events=[
            ChatStreamEvent(type="text_delta", text="EXAMPLE_OK: done."),
            ChatStreamEvent(type="completed", finish_reason="stop"),
        ])
    ]),
)
result = agent.run("完成任务")
print(result.status, result.final_output, result.wal_locator)

Production-grade AgentBuilder

from pathlib import Path
from skills_runtime import AgentBuilder
from skills_runtime.state.wal_protocol import InMemoryWal
from skills_runtime.safety import ApprovalRule, RuleBasedApprovalProvider
from skills_runtime.safety.approvals import ApprovalDecision

provider = RuleBasedApprovalProvider(
    rules=[
        ApprovalRule(tool="read_file", decision=ApprovalDecision.APPROVED),
    ],
    default=ApprovalDecision.DENIED,
)

agent = (
    AgentBuilder()
    .workspace_root(Path(".").resolve())
    .backend(backend)
    .wal_backend(InMemoryWal())
    .approval_provider(provider)
    .event_hooks([lambda ev: print(ev.type)])
    .build()
)

Notes:

• Agent It is recommended to import from skills_runtime.agent Import
• AgentBuilder / Coordinator It is recommended to import from the package root skills_runtime Import
• RunResult.status Currently it should be handled as completed|failed|cancelled|waiting_human Handling

Routing for implementing complex tasks

Route A: single agent + standard tools

Applicable:

• Code modification, reading and writing files, minimal command execution, offline smoke

Approach:

• Use Agent or AgentBuilder
• Tools should preferentially use builtin tools:read_file / apply_patch / file_write / shell_exec
• Keep all side effects in approval_* + tool_call_*

Read first:

• references/recipes-index.md
• references/testing-strategy.md

Route B: Skills-First business capabilities

Applicable:

• Need to package capabilities as reusable skills
• Need mention injection,skill_ref_read、skill_exec

Approach:

• First configure skills.spaces + skills.sources
• Mentions must use the unique valid format:$[namespace].skill_name
• references / actions is off by default; enable it only when explicitly needed
• First run skills preflight, then run skills scan
• If you want to implement skill_exec, first explicitly declare actions

Read first:

• references/config-templates.md
• references/recipes-index.md

Route C: fixed-role multi-agent pipeline

Applicable:

• Analyze → Patch → QA → Report
• Planner → Worker → Reporter
• Roles are fixed and the number is stable

Approach:

• Use Coordinator
• Each role's capabilities should first be consolidated into an independent skill
• The main task text must explicitly include a mention, ensuring that skill_injected

Read first:

• references/api-cheatsheet.md
• references/recipes-index.md

Route D: Dynamic subtasks / parallel collaboration

Applicable:

• The number of subtasks is not fixed
• Additional input is needed during execution
• Needs spawn_agent / send_input / wait

Approach:

• Use collab primitives; do not force-fit Coordinator
• spawn_agent / send_input / close_agent generally must be included in approval governance
• Sub-agents still need to be Skills-First, each maintaining an independent WAL

Read first:

• references/api-cheatsheet.md
• references/safety-and-sandbox.md
• references/recipes-index.md

Route E: Long tasks / waiting for humans / resumable execution

Applicable:

• request_user_input
• ask_human
• waiting_human pause and resume
• WAL replay / fork / resume
• exec sessions engineering-style interaction

Approach:

• First clarify the terminal state and resume semantics
• waiting_human is not a failure state and must be handled separately
• Long sessions should by default include WAL, approval policy, and timeout/resume policy

Read first:

• references/api-cheatsheet.md
• references/testing-strategy.md

Skills implementation checklist

1. Minimal form of the skill directory structure:
   • skills/<skill_name>/SKILL.md
   • references/ Only place materials that need to be read
   • actions/ Only place scripts that are explicitly allowed skill_exec to be called
2. The task text must include a mention:
   • Correct:$[biz:myapp].order-summarizer
3. First do CLI validation:

skills-runtime-sdk skills preflight --workspace-root . --config config/runtime.yaml --pretty
skills-runtime-sdk skills scan --workspace-root . --config config/runtime.yaml --pretty

1. Use only when the overlay explicitly enables it:

   • skills.references.enabled=true
   • skills.actions.enabled=true

2. skill_exec Minimal frontmatter example for :

---
name: artifact_builder
description: "动作型 skill：执行 actions/ 中声明的脚本。"
actions:
  build:
    kind: shell
    argv: ["python3", "actions/build_artifact.py"]
    timeout_ms: 5000
    env:
      ARTIFACT_KIND: "demo"
---

Agent / Workflow implementation checklist

1. Fixed-role collaboration prioritizes Coordinator
2. Dynamic concurrency/additional input prioritizes collab primitives
3. Use by default AgentBuilder to assemble production-grade capabilities:
   • backend
   • WAL
   • approval provider
   • hooks
4. Human intervention processes must check:
   • waiting_human
   • run_waiting_human
   • resume / replay / fork
5. Delivery must provide at least one runnable regression command

Evidence and definition of done

Business delivery must at least have:

1. Runnable entry point:run.py or an equivalent main entry point
2. Minimal overlay: do not hardcode secrets, only declare llm.api_key_env
3. Offline regression:FakeChatBackend + minimal smoke tests
4. WAL evidence:
   • run_started
   • tool_call_*
   • approval_*(if there are side effects)
   • skill_injected / plan_updated / human_request / human_response(depending on the scenario)
   • run_completed / run_failed / run_cancelled / run_waiting_human

Common pitfalls

Pitfall	Correct approach
Directly clone the repository online by default	Locate the local repository first; do not re-clone when a local repository already exists
Only write the agent, not the skill	For complex projects, define skill boundaries first, then write the orchestration
Treat waiting_human as a failure	It is a resumable paused state
Enable approval for all tools by default	For unattended operation, prioritize rule-based approval, defaulting to fail-closed
skill_ref_read / skill_exec use directly	references/actions must be explicitly enabled first
Only look at the final output, not the WAL	Side-effect chains must be auditable and replayable

Local reference navigation

• API and status/events:references/api-cheatsheet.md
• Configuration templates:references/config-templates.md
• Scenario recipes:references/recipes-index.md
• Security/approval/sandbox:references/safety-and-sandbox.md
• Testing and validation:references/testing-strategy.md
• Repository fact snapshot:references/repo-reading-map.md