Skills Executor

Skills Executor 解决的是另一类能力接入：不是给模型一个函数，而是给模型一份标准 SKILL.md guidance，以及它需要的 scripts、references、assets。

它适合 coding-agent guidance、内部操作手册、release review、文档生成等任务。它不是把一段 prompt inline 到业务代码里，也不是替代 Action Runtime。

标准 Skill 目录

一个 Skill 至少有 SKILL.md：

text

release-review/
  SKILL.md
  scripts/
  references/
  assets/

SKILL.md frontmatter 里写 name 和 description：

markdown

---
name: release-review
description: Use when checking release readiness and rollback risk.
---

# Release Review

Follow this checklist before recommending a release or rollback...

Agently 不定义额外的 skill.yaml、skill.json 或作者清单。根目录下这些非标准清单会被拒绝。scripts/、references/、assets/ 里的同名文件只作为普通资源处理。

渐进式披露

Skill 不是把整份手册常驻塞进 prompt。更稳的运行方式是渐进式披露：

阶段	常驻或加载什么	目的
发现 / 选择	`name`、`description`、轻量 decision card、资源索引摘要	让模型或调用方判断“这个 Skill 是否相关”
加载 guidance	选中或 required 后加载完整 `SKILL.md`	让模型获得具体做法、约束和输出要求
按需读取资源	执行时再读 `references/`、`scripts/`、`assets/` 中真正用到的文件	控制上下文成本，并保留读取审计和预算

description 因此不是普通简介，而是选择阶段的关键匹配材料。它要写清“什么任务该用这个 Skill、什么任务不该用、使用后能交付什么”，而不是只写品牌或模块名。

资源文件也不要无差别注入。适合常驻的是元数据和摘要；大段参考材料、模板、脚本、图片或样例，应该在任务确实需要时再读。

运行时优先用 `use_skills`

正常 Agent 运行时，优先在 Agent 上声明 skills：

python

agent.use_skills(
    [{"source": "anthropics/skills", "subpath": "skills/docx"}],
    mode="required",
)

Skills Executor 会先记录 source，在规划时轻量发现 SKILL.md。只有 planner 选中或 required 时，才完整 materialize guidance 和资源。

已经安装的 Skill 可以按 id 使用：

python

agent.use_skills(["release-review"], mode="model_decision")

mode="required" 表示要求使用；mode="model_decision" 表示让模型在候选 Skills 中选择。

安装什么时候用

install_skills(...) 适合本地 Skill 开发和 smoke test：

python

contract = Agently.skills_executor.install_skills("./release-review")
agent.use_skills([contract["skill_id"]], mode="model_decision")

install_skills_pack(...) 适合预热、离线镜像、确定性 CI fixture 或显式 registry 维护：

python

report = Agently.skills_executor.install_skills_pack(
    "anthropics/skills",
    fetch=True,
    subpath="skills/docx",
    trust_level="remote",
)

远程安装会 clone 到本地 registry source cache，再把标准 SKILL.md 包复制进 registry，并记录 source URL、ref、commit、subpath、trust level 和 checksums。安装远程 Skill 不会执行包内 scripts。

安装后的 Skill 根目录仍直接包含 SKILL.md。Agently 只在安装副本内添加 .agently/ 管理目录，用于 install metadata、decision card、resource index 和 checksums。

先解析计划

需要知道会用哪些 Skills 时：

python

plan = await agent.async_resolve_skills_plan(
    "Should this release be blocked?",
    skills=["release-review", "incident-triage"],
    mode="model_decision",
)

Required Skills 保持调用方顺序；多个可选候选由模型排序。

命中不等于能用

计划阶段选中一个 Skill，只说明它和任务相关，不代表它已经获得运行权限。实际能不能用，还要经过宿主应用的策略边界：

闸门	判断什么	由谁负责
选择闸门	Skill 是否和任务匹配；`required` 还是 `model_decision`	Skills planner / 调用方
来源与信任闸门	Skill 是否来自允许来源，安装副本和 checksum 是否可信	Skills registry / host policy
能力加载闸门	Skill 需要 Search、Browse、Workspace、Python、shell、MCP 等能力时是否允许自动加载	host `configure_skill_capabilities(...)`
执行审批闸门	具体 action、脚本、写入、外部副作用是否允许发生	Action / ExecutionEnvironment / PolicyApproval

这能避免一个危险误解：Skill 可以指导模型使用能力，但不能自己授予能力。工具、MCP、脚本、沙箱和文件访问仍由 host 和 Action Runtime 管住。

显式执行 Skills task

当任务要通过 selected Skills 回答时，用 run_skills_task(...)：

python

execution = await agent.async_run_skills_task(
    "Review this release and give a go/no-go recommendation.",
    skills=["release-review"],
    mode="required",
    output={"decision": (str, "go or no-go", True)},
)

print(execution.status)
print(execution.output)
print(execution.skill_logs)

output= 使用和 .output(...) 相同的 schema grammar，描述这次 Skill run 要交付的业务结果形状。output_format= 才控制承载格式。旧的 semantic_outputs= 只是兼容别名，会触发 deprecation warning。

Prompt 链也可以进入 Skill run

python

execution = await (
    agent
    .info({"release": "4.1.2.x"})
    .input("Write a release decision.")
    .output({"decision": (str, "go or no-go", True)}, format="json")
    .async_run_skills_task(skills=["release-review"], mode="required")
)

Skill run 会消费当前 prompt snapshot，把渲染后的 prompt 文本作为 task，并把 output / output_format slot 映射到 Skills 执行参数。显式传入的 output= 和 output_format= 优先于 prompt 推导值。

effort 怎么选

默认执行策略是 single_shot。需要更多过程时，用 effort：

effort	适合
`fast`	低开销 single-shot
`normal`	preflight → research → plan → execute → verify → reflect → finalize
`max`	同一链路，提高 retry 预算，并作为后续 Dynamic Task 升级挂接点
`react`	可用 action 存在时，把 tool/action 规划和执行交给 Action Runtime

Action 相关的 kwargs schema、MCP tools、policy、approval、concurrency 和 Execution Environment 仍由 Action 层拥有，不由 Skills 重新实现。

如果执行过程中出现 pending，它不一定是失败。对一次性直接调用来说，host 可以选择等待、超时或拒绝；在 TriggerFlow 或更长任务里，pending 更适合变成可恢复的审批/策略 interrupt，等外部决定回来后继续执行。

可以用 settings 覆盖档位：

python

agent.set_settings("effort_presets", {
    "fast": {"strategy": "single_shot", "reason_key": "reason_fast", "step_budget": 1},
    "normal": {"strategy": "runtime_chain", "reason_key": "reason", "retry_count": 1},
})

输出格式和 retry

普通 Skill 回答默认 output_format="auto"。Auto 会按 schema 结构选择格式：

扁平纯字符串字段：xml_field。
字符串字段 + 非字符串 typed 字段：hybrid。
控制字段、复杂结构或非 dict 输出：json。

紧凑机器可读结果、model judge 或 JSON-only 下游契约建议显式用 output_format="json"。

python

execution = await agent.async_run_skills_task(
    "Draft a release announcement as HTML.",
    skills=["release-review"],
    mode="required",
    output={"html": (str, "render-ready HTML", True)},
    output_format="xml_field",
)

固定必填字段优先写在 schema 元组第三项。ensure_keys= 只用于条件路径或运行时才决定的路径。多规则 model judge 建议 schema 尽量浅，规则过多时拆成多次 judge。

Stream handler

直接执行 Skills 时，stream_handler 会收到 runtime items，例如：

skills.prompt_only.start
skills.model_stream
skills.prompt_only.done
skills.runtime_chain.*
skills.staged.*
skills.react.*
block.*

skills.model_stream 中会包含 path、value、delta、is_complete。自定义 effort strategy 里如果调用 context.async_request_model(..., stream_handler=...)，模型流回调收到的是 StreamingData。

和 Actions、Dynamic Task 的边界

需求	用什么
给模型一个可调用函数或 MCP tool	Actions
给模型一套标准操作 guidance 和资源	Skills Executor
让模型或应用提交 DAG 并执行	Dynamic Task
应用掌握固定工作流拓扑	TriggerFlow

Skills 可以在执行策略里使用 Actions，但不要把 Action Runtime 重新实现一遍。

常见误用

在业务代码里拼 inline SKILL.md 字符串。
使用根目录 skill.yaml 作为 Skill 定义。
远程安装后假设 scripts 会自动执行。
用 semantic_outputs= 写新代码。新代码用 output=。
把 Skills 当普通 prompt 片段，不维护 resources、decision cards 和执行日志。
以为 Skill 被选中就自动获得工具、MCP、shell 或文件权限。
把 pending 当普通失败处理，而不是按场景映射到审批、等待或恢复。
让 Skills 层重新处理 MCP policy、approval 或 Execution Environment。

下一步

Action Runtime：Action Runtime
Dynamic Task：Dynamic Task
Agent 自动编排：Agent 自动编排
Coding-agent 指引：Coding Agents

Skills Executor ​

标准 Skill 目录 ​

渐进式披露 ​

运行时优先用 use_skills ​

安装什么时候用 ​

先解析计划 ​

命中不等于能用 ​

显式执行 Skills task ​

Prompt 链也可以进入 Skill run ​

effort 怎么选 ​

输出格式和 retry ​

Stream handler ​

和 Actions、Dynamic Task 的边界 ​

常见误用 ​

下一步 ​

Skills Executor

标准 Skill 目录

渐进式披露

运行时优先用 `use_skills`

安装什么时候用

先解析计划

命中不等于能用

显式执行 Skills task

Prompt 链也可以进入 Skill run

effort 怎么选

输出格式和 retry

Stream handler

和 Actions、Dynamic Task 的边界

常见误用

下一步