structured skills

结构化技能

面向代理的结构化技能-从技能目录启动MCP服务器

无需法学硕士

这个库的目标是，它可以在没有任何法学硕士的情况下工作。 技能由您控制的脚本和资源明确定义。与可以执行任意命令的AI代理不同，structured_skills只运行您在技能目录中明确定义的内容。一切都由你写的脚本控制——没有惊喜，没有无限的执行。

它支持什么

• 从包含技能文件夹的根目录中查找技能 SKILL.md.
• 搜索和检查技能和脚本/功能目标。
• 读取具有路径遍历保护的技能目录下的文件。
• 执行：

- 脚本路径位于 scripts/ （例如 echo.py)，或 - 按名称列出函数目标（例如 add).

单文件脚本模式（uv）

存储库包括 structured_skills.py 作为单个文件uv脚本：

uv run structured_skills.py  search [query] --limit 10
uv run structured_skills.py  inspect  [resource_name] [--include-body]
uv run structured_skills.py  execute   --args '{"a":2,"b":3}'

例子：

uv run structured_skills.py tests/fixtures/skills search
uv run structured_skills.py tests/fixtures/skills inspect echo-skill
uv run structured_skills.py tests/fixtures/skills inspect echo-skill --include-body
uv run structured_skills.py tests/fixtures/skills inspect math-skill resources/README.txt
uv run structured_skills.py tests/fixtures/skills execute math-skill add --args '{"a":2,"b":3}'
uv run structured_skills.py tests/fixtures/skills mcp --server-name structured_skills

封装模式

通过项目工具安装/运行：

uv run pytest
uv run skill-tools tests/fixtures/skills search
uv run skill-tools tests/fixtures/skills mcp --server-name structured_skills

控制台脚本入口点为 skill-tools 并映射到 structured_skills.main:main.

Heartbeat守护进程（独立）

该存储库还包括一个独立的仅支持stdlib的调度程序，位于 heartbeat_daemon.py.

运行它：

uv run heartbeat_daemon.py scheduler.toml

scheduler.toml 使用带有命名任务表的扁平根：

version = 1

[daemon]
heartbeat = "1m"
timezone = "UTC"
state_file = "./scheduler-state.json"
shell = "/bin/sh"

[tasks.poll-inbox]
run = "bin/poll-inbox"
every = "5m"

[tasks.daily-summary]
run = "bin/daily-summary"
at = "09:00"

[tasks.backfill-march]
run = "bin/backfill --month 2026-03"
at = "2026-03-15T04:00:00Z"

每个任务都必须定义 run 并且只有一种调度模式：

• every = "" 用于重复运行
• at = "HH:MM" 或 at = "HH:MM:SS" 用于日常跑步
• at = "" 用于一次性跑步

当前支持的可选任务键：

• enabled = true
• timeout = "10m"
• start_at = "..." （为 every 任务）

MCP服务器模式（FastMCP）

structured_skills 可以作为MCP服务器运行，提供三个工具： search, inspect，以及 execute.

• 单文件脚本模式：

- uv run structured_skills.py mcp --server-name structured_skills

• 包装方式：

- uv run skill-tools mcp --server-name structured_skills

技能代理（Python API）

注册表提供 skill() 返回代理对象的方法，允许您调用技能函数和脚本，就像它们是对象上的方法一样：

from pathlib import Path
from structured_skills import SkillRegistry

registry = SkillRegistry(Path("skills"))

# Call a function directly
proxy = registry.skill("math-skill")
result = proxy.add(a=2, b=3)  # Returns 5

# Call a script
result = proxy.math_ops(a=2, b=3)  # Returns 5

# Works with positional args too
result = proxy.add(2, 3)  # Returns 5

代理人：

• 发现技能中的函数和脚本 scripts/ 目录
• 允许您将它们称为带有关键字或位置参数的Python方法
• 提高 AttributeError 如果函数/脚本不存在
• 提高 TypeError 对于重复的参数值

Python API

主要进口：

from pathlib import Path
from structured_skills import SkillRegistry, SkillToolsBuilder

registry = SkillRegistry(Path("tests/fixtures/skills"))
result = registry.execute("math-skill", "add", {"a": 2, "b": 3})
print(result)