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 areshell,file,http,script, andcode_exec.metadata.version: optional version. Defaults to1.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’sscripts/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
codeparameter — there’s noscripts/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_execrefuses every call rather than running unsandboxed — checkyanshi doctororyanshi skill inspect --explain-permissionsfor 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.mdand.txtfiles in deterministic order and injects them into the persona.[[knowledge]]:skill.tomlentries 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. Omittingbackendkeeps 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 singlerag_searchtool; 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 underchunk_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 (requiresyanshi-rag’scode-chunkingfeature; 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.