Tools, Skills & Experts¶
Built-in tools and permission tiers¶
Every tool has a permission tier that decides how it is confirmed:
| Tier | Behavior |
|---|---|
| Auto | No prompt; the model calls it directly |
| Confirm | Prompts [y]es / [n]o / [a]lways (this conversation) / [s]top (abort turn) |
| Dangerous | Only y / n — destructive operations are asked every time; the "always" cache cannot bypass them |
Explicit policy denies in permissions.toml apply even to AUTO tools and
auto_approve runs. See Permissions.
Filesystem¶
| Tool | Permission | Description |
|---|---|---|
read_file |
Auto | Read file contents (line offset/limit) |
write_file |
Confirm | Write a file, returns a unified diff |
list_directory |
Auto | List directory contents with types and sizes |
create_directory |
Confirm | Create directories including nested parents |
delete_file |
Dangerous | Delete a file (irreversible) |
delete_directory |
Dangerous | Delete a directory tree (irreversible) |
search_files |
Auto | Search files by glob pattern |
move_file |
Confirm | Move / rename a file or directory |
Shell¶
run_command (Confirm) executes shell commands. Dangerous-mode commands are
intercepted and read-only commands are classified automatically. A timeout
argument (seconds, default 600, AGENTICX_COMMAND_TIMEOUT) caps the run; on
expiry the whole process group is killed, so a pipeline does not outlive the
timeout.
Network (optional web / browser extras)¶
| Tool | Permission | Description |
|---|---|---|
web_search |
Auto | DuckDuckGo search: titles, URLs, snippets |
scrape_web |
Auto | Page plain text via Playwright headless browser (renders JS SPAs) |
scrape_web_html |
Auto | Rendered HTML source |
scrape_web_screenshot |
Auto | Screenshot saved as an image file |
Browser tools need a separate Playwright runtime setup after installing the
extra. Camera tools (camera_capture, camera_record, both Confirm) need
the camera/vision media extras.
Session & configuration (always available)¶
switch_model, switch_provider, list_models, capability_list (Auto);
capability_enable, capability_disable, mcp_connect, mcp_disconnect
(Confirm); mcp_list_services, create_plan, complete_step,
get_plan_status (Auto).
Subagents (after enabling local.subagent / local.delegate)¶
subagent_invoke, review_code, write_tests, generate_docs, delegate,
delegate_parallel — all Auto. See
Subagents, Hooks & Memory.
Platform tools (after enabling bailian.cli)¶
The full Bailian CLI command set is registered as bailian_<command_path>
tools (e.g. bailian_text_chat, bailian_image_generate). Read verbs
(list/get/status/search) are Auto; write verbs (generate/upload/delete) are
Confirm. Schemas come from bl config export-schema and are cached for 24h.
See Platform integration.
Capabilities¶
Optional tool groups are gated by capabilities:
agenticx> /capability list
agenticx> /capability enable bailian.cli # takes effect after restart
agenticx> /capability disable local.subagent
agenticx> /capability reload
Commands for disabled capabilities are intercepted with an enable hint instead of failing on credentials. Installing an extra never grants an App permissions by itself.
Custom tools¶
Layer 1 — configuration as program (no code)¶
custom-extensions.toml (workspace ./.agenticx/ overrides global
~/.config/AgenticX/; files are chmod 600) registers providers, HTTP tool
groups, and shell tools at startup. /dev reload hot-reloads it.
HTTP tool group:
[[capabilities]]
key = "moonshot.web"
display = "Moonshot web search"
auth = "bearer:$MOONSHOT_API_KEY"
[[capabilities.tools]]
name = "web_search"
description = "Web search for real-time information"
endpoint = "https://api.moonshot.cn/v1/tools/web_search"
http_method = "POST"
permission = "auto" # auto / confirm / dangerous
params = [
{name="query", type="string", required=true, description="Search keywords"},
{name="count", type="integer", default=10, description="Number of results"},
]
body_template = '{"query": {{query}}, "count": {{count}}}'
result_jsonpath = "data.results" # optional dot-path extraction
Auth formats: bearer:$ENV, apikey-header:HeaderName:$ENV, none.
Body templates use Mustache {{var}} placeholders (values are JSON-encoded
before substitution).
Shell tool — wrap a command as an LLM-callable tool:
[[shell_tools]]
name = "check_port"
description = "Check whether a TCP port is open"
command_template = "nc -z -w 3 {{host}} {{port}}"
params = [
{name="host", type="string", required=true},
{name="port", type="integer", required=true},
]
permission = "auto"
Parameterized {{name}} values are passed as literal process arguments,
even when the placeholder is quoted. Parameterized pipelines, redirections,
shell interpreters, and executable Python code/module names are rejected;
for complex workflows call a trusted executable script with literal
arguments. Constant commands without parameters keep explicit shell
behavior.
Provider declarations ([[providers]]) and API-key security rules are
covered in Configuration.
Layer 2 — real Python tools¶
Register a ToolDefinition with the runtime registry, or use the @tool
decorator (the parameter schema is derived from type hints):
from dashscope_agenticx.tools.registry import (
PermissionLevel,
ToolDefinition,
tool,
)
@tool("check_complexity", "Check cyclomatic complexity of a file",
permission=PermissionLevel.AUTO)
async def check_complexity(path: str) -> str:
...
Inside a Skill package, expose a register(registry) function in tools.py;
tool names are automatically prefixed with the package name
(my-review_check_complexity):
from dashscope_agenticx.tools.registry import PermissionLevel, ToolDefinition
async def check_complexity(path: str) -> str:
...
def register(registry):
registry.register(ToolDefinition(
name="check_complexity",
description="Check the cyclomatic complexity of a file",
func=check_complexity,
permission=PermissionLevel.AUTO,
parameters={
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"],
},
))
The /dev command family scaffolds all of this interactively:
/dev provider|capability|skill|tool add|list|rm, /dev model add,
/dev debug tools|schema|call|prompt, /dev test provider <name>.
The legacy .agenticx/plugins/ auto-loading mechanism is removed — use
Layer-1 TOML, hooks, or Layer-2 modules instead.
Skills¶
Skills are preset prompt templates invoked with /skill. Two forms:
single-file .md and directory packages. At startup
~/.config/AgenticX/skills/ and .agenticx/skills/ are scanned; a
same-named workspace skill overrides the global one.
Single-file skill¶
YAML frontmatter defines metadata; the body is the prompt template with
{arg} placeholder substitution:
---
name: review
description: Code review with improvement suggestions
arguments: [file]
---
Please perform a code review of the following file, focusing on:
1. Potential bugs
2. Performance issues
3. Readability
File: {file}
Invoke with /skill review src/main.py. Single-file skills are injected
into the system prompt as a compact catalog (args, description, MCP
dependency status).
Directory-package skill¶
For custom Python tools or dedicated hooks:
.agenticx/skills/my-review/
├── skill.toml # metadata, activation rules
├── prompt.md # prompt template
├── tools.py # optional: custom tools (prefixed my-review_<tool>)
└── hooks.toml # optional: hooks scoped to this skill
# skill.toml
name = "my-review"
version = "1.0.0"
description = "Custom code review with a complexity check tool"
author = "your-name"
always_active = false
triggers = ["*review*", "*audit*"]
always_active = true:prompt.mdis injected every turn.triggers: glob patterns; the skill activates when the user message matches any pattern.
Lifecycle¶
/skill list # single files + packages
/skill reload # rescan directories
/skill enable|disable <name> # force state (ignore triggers)
/skill install ./my-review # local path / git+URL / tar.gz URL / registry name[@version]
/skill link ./my-review # dev symlink; /skill reload picks up edits
/skill update <name>|--all
/skill uninstall <name>
/skill search review # installed + registry
/skill publish ./my-review # validate + package tar.gz into .dist/
Installation records live in .agenticx/skills/.agenticx-skills.json.
URL packages undergo tar path-traversal validation (including link targets)
and a 50 MB size limit.
A registry is a static TOML/JSON/YAML index — no server dependency:
# index.toml
[[skills]]
name = "code-review"
version = "1.2.0"
description = "Code review (security+style+performance)"
source = "git+https://github.com/agenticx/skills/code-review.git"
tags = ["python", "review"]
Point skill_registry in .agenticx/config.toml at the index URL or a
local file. Without a registry, /skill install <name> requires a local
path or git URL.
Experts¶
Configuration is the Agent. An Expert is a ready-to-use .agenticx/
profile — persona, providers, skills, knowledge index — with no bootstrap
code. Downloading one is the recommended starting point for a new Agent:
agenticx expert # list templates
agenticx expert download basic-chat # merge into ./.agenticx/
agenticx # already the Expert's Agent
- The Expert's
.agenticx/tree is merged into the workspace; root-level files (README etc.) are collected into.agenticx/too. - Same-named files are backed up to
.agenticx/backup/(single rolling backup);/expert restoreundoes the merge — restoring overwritten files and removing added ones. - Customize by plain-text editing:
system-prompt.md(persona),skills/*.md(task templates),references/*.md(always-on knowledge, injected at startup),custom-extensions.toml(providers/tools).
Profiles download from apps/<name>/ in
dashscope/dashscope-agenticx-experts
(branch main by default). Only the 1.0 App Catalog layout is supported.
Override the source with expert_repo / expert_branch in global config
or --repo.
Bundled examples: basic-chat (minimal general assistant with web search),
dashscope-sdk-expert (SDK Q&A with an auto-generated knowledge index and
/skill update-sdk refresh), and bailian-expert.
Experts vs App Bundles¶
Expert downloads contain role/configuration data — not executable Python,
shell tools, or run hooks — and are not registered as Apps. A production
App Bundle adds a versioned app.toml manifest, Runtime compatibility
range, permission diffs, and checksum verification, managed with
agenticx app list|install|info|verify|update. app install previews new
permissions before writing files and registers the bundle under
.agenticx/apps/ without activating its profile. A checksum proves content
identity, not publisher authenticity; a local trust flag is not a verified
digital signature.