AgentSkillsCN

x07-agent-playbook

采用以代理为核心的流程与设计规范，借助已发布的工具链构建 X07 程序（无需仅依赖仓库）。标准执行方式为：`x07 run`。

SKILL.md
--- frontmatter
name: x07-agent-playbook
description: Agent-first workflow and design rails for building X07 programs with the released toolchain (no repo-only dependencies). Canonical execution is via `x07 run`.
metadata:
  short-description: X07 agent workflow + rails
  version: 0.1.0
  kind: docs

x07-agent-playbook

This skill sets the baseline workflow and constraints for autonomous agents writing X07 programs. It assumes end-users only have the released toolchain binaries, not the toolchain source repo.

Tooling

See references/tooling.md.

Execution should go through x07 run (single front door). The standalone OS runner binary (x07-os-runner) remains available for expert usage, but is not part of the default agent loop.

If the task needs OS worlds or native deps (curl/openssl, etc), run x07 doctor early and follow its suggestions.

Canonical docs:

Single canonical agent loop (edit → run → test)

  1. •

    Create or edit x07AST JSON (*.x07.json).

  2. •

    Run in the correct capability world (canonical: x07 run):

    • •default run (uses x07.json default_profile): x07 run
    • •policy-enforced run: x07 policy init --template <cli|http-client|web-service|fs-tool|sqlite-app|postgres-client|worker|worker-parallel> (starting point; review and extend), then x07 run --profile sandbox (optionally add --allow-host ... / --deny-host ... to materialize derived policies)

    x07 run runs the canonical auto-repair loop by default (format → lint → quickfix, repeatable). Use:

    • •--repair=off to disable auto-repair (debugging)
    • •--repair=memory to stage repairs under .x07/repair/_staged/ without editing source files
    • •--repair=write (default) to write repairs back to source files
    • •--repair-max-iters N to bound iterations (default: 3)

    For CLI-style programs that expect argv_v1, pass process args after -- and x07 run will encode them into input bytes:

    • •x07 run -- tool --help
  3. •

    If the project uses dependencies, update the lockfile:

    • •x07 pkg lock --project x07.json

    If any dependency declares required helper packages via meta.requires_packages, x07 pkg lock may also update x07.json to add those transitive deps.

  4. •

    If you need a distributable native executable (end-user CLI binary, no toolchain required at runtime), bundle it:

    • •x07 bundle --profile os --out dist/app
    • •x07 bundle --profile sandbox --out dist/app (policy enforced)
  5. •

    If you need explicit diagnostics or tighter control than the default auto-repair loop:

    • •x07 fmt / x07 lint / x07 fix / x07 ast apply-patch

Keep each iteration small and checkable; if a repair loop does not converge quickly, stop and re-evaluate the approach.

Note: paths above assume a project scaffold (x07 init). In a publishable package repo (x07 init --package), format/lint the module files under modules/ and run tests via x07 test --manifest tests/tests.json.

Recommended project layout (single canonical shape)

For app projects (x07 init):

  • •x07.json: project manifest (x07.project@0.2.0)
  • •x07.lock.json: project lockfile (or lockfile configured in x07.json)
  • •src/main.x07.json: entry
  • •src/: module roots
  • •.x07/deps/<name>/<version>/: fetched dependencies (when using x07 pkg lock)
  • •tests/tests.json: test manifest (generated by x07 init in new projects)

For publishable package repos (x07 init --package):

  • •x07-package.json: package manifest (publish contract for x07 pkg publish)
  • •x07.json: minimal project manifest for local tests
  • •modules/: module roots (publishable modules layout)
  • •tests/tests.json: test manifest

Choosing packages (canonical)

Prefer the capability map (one default choice per capability):

Common non-web building blocks for agents:

  • •text.core → ext-text (trim/split/join/find/lines)
  • •text.unicode → ext-unicode-rs (normalize/casefold/segment)
  • •math.bigint → ext-bigint-rs
  • •math.decimal → ext-decimal-rs
  • •data.cbor → ext-cbor-rs
  • •data.msgpack → ext-msgpack-rs
  • •checksum.fast → ext-checksum-rs
  • •diff.patch → ext-diff-rs
  • •compress.zstd → ext-compress-rs
  • •fs.globwalk → ext-path-glob-rs (run-os*)

Add deps with x07 pkg add NAME@VERSION --sync (choose NAME@VERSION from the capability map).

If you don’t know which package provides an import, use x07 pkg provides <module-id>.

Agent-first design rails

See references/design-rails.md.

For a built-in language/stdlib reference (toolchain-only), use x07 guide.

By-example docs (recommended)