Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Skills

Skills package reusable agent capabilities for Yanshi. A skill can define:

  • Agent instructions and persona.
  • Runtime limits such as model name, max iterations, and token budget.
  • Built-in tools with sandbox constraints.
  • Script tools from a local scripts/ directory.
  • MCP servers whose remote tools are discovered and registered at runtime.
  • Knowledge files and references/ documents injected into the agent context.
  • Session or SQLite-backed memory configuration.

Use a Skill when behavior should be portable across CLI runs, agent runtimes, and future workflow integrations. Use a plain workflow when each step is deterministic and should be represented as a fixed DAG.

Directory Layout

The recommended layout is:

my-skill/
  SKILL.md
  references/
    policy.md
  scripts/
    helper.sh

SKILL.md is the recommended standard entrypoint. skill.toml is still supported for compatibility and for deployments that need an explicit structured override. When both files exist, skill.toml is loaded and overrides SKILL.md.

SKILL.md

Minimal portable skill:

---
name: code-reviewer
description: Review code for correctness, security, and maintainability.
allowed-tools: file shell
metadata:
  version: "1.0.0"
---

# Code Reviewer

Inspect the requested files and report findings first. Prioritize correctness,
security, data loss, and missing test coverage.

Important fields:

  • name: lowercase identifier using letters, digits, and hyphens.
  • description: short explanation of what the skill does and when to use it.
  • allowed-tools: optional space-delimited built-in tool list. Supported values are shell, file, http, script, and code_exec.
  • metadata.version: optional version. Defaults to 1.0.0.
  • Markdown body: becomes the base persona/system instructions.

For the complete format reference, see SKILL_FORMAT.md.

Built-In Tools

Skills can expose built-in local tools through allowed-tools in SKILL.md or [[tools]] in skill.toml.

---
name: local-helper
description: Inspect local files and run approved commands.
allowed-tools: file shell script
---

# Local Helper

Use local files and scripts to answer implementation questions.

The current built-ins are:

  • file: read, write, and list files under the active sandbox policy.
  • shell: execute allowed commands.
  • http: make HTTP requests subject to allowed domain policy.
  • script: execute scripts from the skill’s scripts/ directory.
  • code_exec: run LLM-generated Python in a strongly-isolated, ephemeral, network-off sandbox — see Code Execution Tool below.

For tighter sandbox constraints, use skill.toml:

[skill]
name = "repo-helper"
version = "1.0.0"
description = "Inspect one repository safely"

[persona]
role = "Answer questions using the repository files and approved commands."

[[tools]]
name = "file"
allowed_paths = ["./src", "./docs"]

[[tools]]
name = "shell"
allowed_commands = ["cargo", "rg"]
max_exec_time_secs = 60

Script Tools

Declare the script tool and place executable helpers in scripts/:

my-skill/
  SKILL.md
  scripts/
    summarize.sh

When the skill is built, Yanshi registers one script tool rooted at that directory. The script tool always validates wrapper parameters with JSON Schema before execution. By default it only accepts a plain script filename ending in .py, .sh, or .js, plus optional args; extra top-level parameters are rejected.

Script parameters can be further constrained with a JSON schema through skill.toml:

[[tools]]
name = "script"

[tools.parameters]
type = "object"
required = ["script"]

[tools.parameters.properties.script]
type = "string"

[tools.parameters.properties.args]
type = "array"

For sandboxing, script tools resolve and canonicalize the target path before execution. Symlinks or paths that escape scripts/ are rejected. If a skill declares only the script tool and omits allowed_commands, Yanshi allows only the known script interpreters: python3, bash, and node.

Code Execution Tool

script only runs author-signed files that existed in scripts/ before the run started — it never executes content the model wrote this turn. code_exec fills that gap: it runs Python source the LLM generates in the conversation itself, inside a strongly-isolated container/microVM (Apple’s container CLI or rootless Podman), never through the OS-sandbox tier script/shell use. See RFC_LLM_CODE_EXECUTION.md for the full design rationale.

[[tools]]
name = "code_exec"

Declare it the same way as any other tool — no additional constraint fields are supported in this version (allowed_commands / allowed_paths / allowed_domains / os_sandbox are ignored for code_exec; none of its isolation is author-configurable):

  • One call runs one Python script, passed inline as the code parameter — there’s no scripts/ directory involvement and no persistent state between calls.
  • Every call gets a fresh, disposable working directory, discarded when the call returns.
  • No network access at all, always — there is no opt-in yet (an egress allowlist proxy is a planned prerequisite before that changes).
  • Resident memory, CPU time, and process count are capped (256 MiB / 30 CPU-seconds / 32 processes as of this writing) and enforced by the container engine.
  • Requires a container engine on the host. If none is available, code_exec refuses every call rather than running unsandboxed — check yanshi doctor or yanshi skill inspect --explain-permissions for the current status.
  • Only Python is supported in this version.

MCP Tools

Skills can mount MCP servers declaratively. Yanshi starts the configured server, calls list_tools, and registers each discovered remote tool in the local ToolRegistry.

---
name: mcp-basic
description: Demonstrate a Skill that exposes tools from a local MCP server.
metadata:
  version: "1.0.0"
mcp_servers:
  - name: local-demo
    command: python3
    args:
      - ./server.py
    timeout_secs: 30
---

# MCP Basic

Use the local MCP demo tools when the user asks to echo text or inspect status.

MCP tool names are exposed as:

mcp_<server_name>_<tool_name>

Names are lowercased, non-alphanumeric characters are normalized to underscores, and duplicate public names fail validation. For example, server local-demo tool echo becomes mcp_local_demo_echo.

Relative MCP command parts such as ./server.py are resolved from the skill directory. MCP connect, discovery, and tool calls use timeout_secs, defaulting to 30 seconds.

MCP startup is governed by [security] in skill.toml or matching frontmatter fields in SKILL.md. By default, Yanshi allows only common stdio server launchers (python, python3, node, npx, uvx), limits a skill to 4 MCP servers, clamps MCP timeouts to 1-120 seconds, and admits at most 4 concurrent calls per server. If an MCP server forwards environment variables, list their names in mcp_env_allowlist; audit logs record command names and env keys, never env values.

Tool execution is also governed at call time. Set tool_permission_allowlist under [security] to restrict registered tools by permission category such as filesystem_read, filesystem_write, process_exec, network, mcp, or workflow. Empty means all registered tool permissions are allowed.

See MCP_SKILLS.md for the MCP Skills usage guide and MCP_SKILLS_INTEGRATION.md for the deeper design notes.

Knowledge And References

There are two ways to add local context:

  • references/: standard Skill directory for Markdown or text files. Yanshi loads .md and .txt files in deterministic order and injects them into the persona.
  • [[knowledge]]: skill.toml entries for explicit files or glob patterns.

Example:

[[knowledge]]
path = "./knowledge/*.md"
description = "Project operating notes"

Knowledge tiers — backend (P-A4.2)

Each [[knowledge]] entry chooses how its content reaches the agent via an optional backend field:

  • backend = "files" (default) — the file content is inlined directly into the agent’s system prompt (the persona’s “Knowledge Context”). Best for small, always-relevant material. Omitting backend keeps this behaviour, so existing skills are unaffected.
  • backend = "rag" — the file content is indexed into an in-memory keyword (BM25) index and exposed to the agent as a single rag_search tool; the agent retrieves only the relevant passages on demand instead of carrying the whole corpus in its prompt. Best for large reference material that would otherwise blow the token budget. No vector database or network is required — the skill’s bundled files are indexed locally.
# Small, always-needed → inlined into the prompt.
[[knowledge]]
path = "./knowledge/house-style.md"

# Large reference corpus → searchable via the rag_search tool.
[[knowledge]]
path = "./knowledge/api-reference/*.md"
backend = "rag"

All backend = "rag" entries across a skill share one rag_search tool, so the model sees a single “search the knowledge base” affordance. references/ documents are always files-tier (inlined).

Chunking rag-tier knowledge — chunk_strategy

By default each rag-tier file is indexed as one whole-file document. Set chunk_strategy on a [[knowledge]] entry to split it into smaller, independently-citable chunks instead:

[[knowledge]]
path = "./knowledge/manual.md"
backend = "rag"
chunk_strategy = "paragraph"
chunk_size = 200
chunk_overlap = 0

chunk_strategy accepts:

  • "fixed_size" — splits at fixed character offsets.
  • "sentence" — splits on sentence boundaries.
  • "recursive" — splits on a cascade of separators (paragraphs, then sentences, then words) to stay under chunk_size.
  • "paragraph" — splits on blank lines; never splits a paragraph across two chunks.
  • "heading" — splits Markdown documents at heading boundaries.
  • "code_ast" — splits Rust source at function/impl boundaries (requires yanshi-rag’s code-chunking feature; source must be valid Rust).
  • "semantic" — splits at topic boundaries detected via embedding similarity between sentences, instead of a fixed size. Requires an OpenAI API key — see below.

chunk_size (characters, default 1000) and chunk_overlap (characters, default 100) apply to every strategy above.

Semantic chunking

chunk_strategy = "semantic" additionally accepts:

[[knowledge]]
path = "./knowledge/manual.md"
backend = "rag"
chunk_strategy = "semantic"
embedding_model = "text-embedding-3-small"   # default; also "text-embedding-3-large", "text-embedding-ada-002"
chunk_similarity_threshold = 0.6             # default; lower = more, smaller chunks
chunk_min_segment_size = 20                  # default; minimum sentence-segment length in characters
chunk_buffer_percentile = 0.25               # default; dynamic-threshold percentile

Semantic chunking requires the OPENAI_API_KEY environment variable to be set — it calls OpenAI’s embeddings API to compare sentences. Building a skill with chunk_strategy = "semantic" and no API key set fails fast with a validation error explaining this. Every other chunk_strategy option above works fully offline.

Multi-query retrieval — query_rewrite

Set query_rewrite = "split" on a rag-tier [[knowledge]] entry to decompose a caller’s query on conjunctions/punctuation before searching (for example, “find X and explain Y” is searched as two sub-queries and results merged). All rag-tier entries in a skill share one rag_search tool, so this is effectively a skill-wide setting: the first entry (in manifest order) that sets query_rewrite wins.

Memory

Skills can configure memory in skill.toml:

[memory]
type = "sqlite"
db_path = "~/.yanshi/memory/repo-helper.db"
window_tokens = 8000

Supported values are:

  • session: in-memory session window.
  • sqlite: persistent SQLite-backed memory.
  • none: currently maps to the default in-memory session behavior while disabling persistent storage.

semantic appears in the manifest type but is not enabled by the current validator. Treat semantic memory as upcoming runtime work, not as a stable Skill feature.

CLI Workflow

Create a new skill scaffold:

cargo run -p yanshi-cli -- skill init ./my-skill \
  --description "Describe when this skill should be used."

The scaffold includes SKILL.md, README.md, references/example.md, scripts/hello.py, and tests/smoke.sh.

Inspect a shared registry index:

cargo run -p yanshi-cli -- skill index validate yanshi-skills/examples/skills.index.toml
cargo run -p yanshi-cli -- skill index list yanshi-skills/examples/skills.index.toml
cargo run -p yanshi-cli -- skill index resolve yanshi-skills/examples/skills.index.toml mcp-demo

skills.index.toml is a local, organization-owned catalog. Each entry pins a skill version and can optionally lock the manifest with manifest_sha256. Relative path values are resolved from the index file directory, so a repository can keep shared skills and the index side by side. The checked-in example resolves mcp-demo to yanshi-skills/examples/skills/mcp-basic. See SKILL_REGISTRY.md for the schema, compatibility policy, locking model, install flow, and future remote registry boundaries.

Install a skill from a local registry index:

cargo run -p yanshi-cli -- skill install yanshi-skills/examples/skills.index.toml mcp-demo \
  --dir /tmp/yanshi-skills
cargo run -p yanshi-cli -- skill validate /tmp/yanshi-skills/mcp-basic

skill install copies the resolved local skill directory into the target skills directory using the canonical skill name as the destination directory. It refuses to overwrite an existing skill unless --force is passed. The default target is ~/.yanshi/skills.

Browse a Skill catalog that groups one or more registry indexes:

cargo run -p yanshi-cli -- skill marketplace list yanshi-skills/examples/marketplace.toml
cargo run -p yanshi-cli -- skill marketplace resolve yanshi-skills/examples/marketplace.toml mcp-demo

Marketplace files are Skill catalogs only. They point at registry indexes and print the matching yanshi skill install <index_file> <skill> command; install still validates and copies from the resolved registry index.

Validate a skill:

cargo run -p yanshi-cli -- skill validate yanshi-skills/examples/skills/mcp-basic

List all tools exposed by a skill:

cargo run -p yanshi-cli -- skill list-tools yanshi-skills/examples/skills/mcp-basic

Run the skill test gate:

cargo run -p yanshi-cli -- skill test yanshi-skills/examples/skills/mcp-basic

skill test runs manifest validation, tool discovery, and built-in minimal regressions. For the default scaffold it invokes scripts/hello.py through the script tool. Pass --smoke to also run tests/smoke.sh when present.

Run one message through a skill:

cargo run -p yanshi-cli -- skill run yanshi-skills/examples/skills/mcp-basic \
  --message "echo hello through MCP"

Start an interactive session:

cargo run -p yanshi-cli -- skill chat yanshi-skills/examples/skills/mcp-basic

skill run and skill chat build a ReActAgent from the manifest, attach the built tool registry, and execute through the agent runtime. Use --trace with skill run to print the structured runtime trace.

Current Boundaries

The current Skill path covers packaging, validation, tool registry construction, MCP tool discovery, MCP tool execution, prompt-time references, and agent runtime execution. Skills are capability packages, not dynamically loaded plugins. See EXTENSIBILITY_MODEL.md for the boundary between Rust nodes, Tools, MCP, Skills, Skill catalogs, and future plugins.

Known follow-up work is tracked in the project roadmap and local task queue, including:

  • Agent runtime disable switch.
  • Semantic memory query APIs and agent loop memory hooks.
  • Memory budget and summarization strategy.
  • More examples for Skill-to-MCP calls.