跳转至

Skills

Skills 是 Datus-agent 的技能发现和加载系统，遵循 agentskills.io 规范。它通过 SKILL.md 文件实现模块化、按需扩展的能力。

快速开始

本教程演示如何使用 report-generator 技能与加州学校数据集生成分析报告。

步骤 1：创建技能

创建包含 SKILL.md 文件的技能目录：

~/.datus/skills/
└── report-generator/
    ├── SKILL.md
    └── scripts/
        ├── generate_report.py
        ├── analyze_data.py
        ├── validate.sh
        └── export.sh

SKILL.md 内容：

---
name: report-generator
description: Generate analysis reports from SQL query results with multiple output formats (HTML, Markdown, JSON)
tags: [report, analysis, visualization, export]
version: "1.0.0"
allowed_commands:
  - "python:scripts/*.py"
  - "sh:scripts/*.sh"
---

# Report Generator Skill

This skill generates professional analysis reports from SQL query results.

## Features

- **Multiple Formats**: Export to HTML, Markdown, or JSON
- **Data Analysis**: Automatic statistical analysis and insights

## Usage

### Generate a Report

python scripts/generate_report.py --input results.json --format html --output report.html

Options:
- `--input`: Input data file (JSON or CSV)
- `--format`: Output format (html, markdown, json)
- `--output`: Output file path
- `--title`: Report title (optional)

步骤 2：在 agent.yml 中配置技能

skills:
  directories:
    - ~/.datus/skills
    - ./skills
  warn_duplicates: true

permissions:
  default: allow
  rules:
    # 技能加载需要确认
    - tool: skills
      pattern: "*"
      permission: ask
    # 技能脚本执行需要确认
    - tool: skill_bash
      pattern: "*"
      permission: ask

Tip

为 skills 和 skill_bash 使用 ask 权限，在执行前需要手动确认，有助于防止意外或危险操作。

步骤 3：在聊天会话中使用技能

启动聊天会话并提出问题：

> What is the highest eligible free rate for K-12 students in the schools
> in Alameda County? Generate a report using the final result.

Agent 将执行以下操作：

  1. 加载技能 - 当需要生成报告时，LLM 调用 load_skill(skill_name="report-generator") 获取技能指令。

  2. 执行 SQL 查询 - 查询加州学校数据库以获取答案。

  3. 生成报告 - 执行技能脚本创建报告：

    skill_execute_command(
    skill_name="report-generator",
    command="python scripts/generate_report.py --input results.json --format markdown --title 'Alameda County K-12 Free Rate Analysis'"
)

聊天会话展示技能加载和报告生成 聊天会话展示技能加载和报告生成

步骤 4：查看生成的报告

报告将在技能的工作目录中生成：

生成的 Markdown 报告展示分析结果

权限系统

权限系统控制哪些技能和工具可供 Agent 使用。

权限级别

级别 行为
allow 技能可用且可自由使用
deny 技能对 Agent 隐藏（不会出现在提示中）
ask 每次使用前需要用户确认

配置示例

permissions:
  default: allow
  rules:
    # 默认允许所有技能
    - tool: skills
      pattern: "*"
      permission: allow

    # 数据库写操作需要确认
    - tool: db_tools
      pattern: "execute_sql"
      permission: ask

    # 隐藏内部/管理技能
    - tool: skills
      pattern: "internal-*"
      permission: deny

    # 潜在危险技能需要确认
    - tool: skills
      pattern: "dangerous-*"
      permission: ask

模式匹配

模式使用 glob 风格匹配：

  • * 匹配任意内容
  • report-* 匹配以 "report-" 开头的技能
  • *-admin 匹配以 "-admin" 结尾的技能

节点特定权限

为特定节点覆盖权限：

agentic_nodes:
  chat:
    skills: "report-*, data-*"  # 仅暴露匹配的技能
    permissions:
      rules:
        - tool: skills
          pattern: "admin-*"
          permission: deny

在 Subagent 中使用技能

技能可以配置为在隔离的 Subagent 上下文中运行，适用于复杂任务。

配置 Subagent 执行

在 SKILL.md frontmatter 中添加 context: fork 并指定 agent 类型：

---
name: deep-analysis
description: Perform comprehensive data analysis with multiple iterations
tags: [analysis, research]
context: fork
agent: Explore
---

# Deep Analysis Skill

This skill runs in an isolated Explore subagent for thorough investigation.

## When to Use
- Complex multi-step analysis
- Tasks requiring extensive exploration
- Investigations that may take multiple turns

可用的 Subagent 类型

Agent 类型 用途
Explore 代码库探索、文件搜索、理解结构
Plan 实现规划、架构决策
general-purpose 多步骤任务、复杂研究

示例：带 Subagent 的研究技能

---
name: codebase-research
description: Research codebase patterns and architecture
context: fork
agent: Explore
user_invocable: true
---

# Codebase Research

When invoked, this skill spawns an Explore subagent to:
1. Search for relevant files and patterns
2. Analyze code structure
3. Report findings back to the main conversation

调用控制

字段 默认值 描述
disable_model_invocation false 如为 true，仅用户可通过 /skill-name 调用
user_invocable true 如为 false，从 CLI 菜单隐藏（仅模型调用）

SKILL.md 参考

Frontmatter 字段

字段 必需 描述
name 是 唯一技能标识符
description 是 在可用技能列表中显示的简短描述
tags 否 用于分类的标签列表
version 否 语义版本字符串
allowed_commands 否 允许的脚本模式列表
context 否 设为 "fork" 以在 subagent 中运行
agent 否 Subagent 类型：Explore、Plan、general-purpose
disable_model_invocation 否 如为 true，仅用户可调用
user_invocable 否 如为 false，从 CLI 菜单隐藏

命令模式格式

prefix:glob_pattern

示例：

  • python:* - 允许任意 python 命令
  • python:scripts/*.py - 仅允许 scripts/ 目录中的脚本
  • sh:*.sh - 允许 shell 脚本
  • python:-c:* - 允许 python -c 内联代码

安全特性

  • 命令仅在匹配允许的模式时执行
  • 工作目录锁定在技能位置
  • 超时强制执行（默认：60 秒）
  • 环境变量：SKILL_NAME、SKILL_DIR

故障排除

技能未被发现

  1. 检查技能目录是否在 skills.directories 配置中
  2. 验证 SKILL.md 具有有效的 YAML frontmatter（在 --- 标记之间）
  3. name 和 description 字段都是必需的

脚本执行被拒绝

  1. 验证命令是否匹配 allowed_commands 模式
  2. 确保先通过 load_skill() 加载了技能
  3. 检查模式格式：prefix:glob_pattern

调试日志

启用调试日志：

export DATUS_LOG_LEVEL=DEBUG