Skills Executor

语言： English · 中文

Agently Skills 遵循标准 Skills 目录：SKILL.md 是能力定义，scripts/、 references/、assets/ 是可选资源目录。Agently 不定义额外的 Skill 作者清单。

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

# Release Review

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

声明和安装

正常 Agent 运行时，优先在 Agent 上用 use_skills(...) 声明 Skills。 Skills Executor 会像 Action candidate 一样先记录 source，在规划时轻量发现 SKILL.md，只有 planner 选中或 required 时才完整安装 Skill 和资源。

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

install_skills_pack(...) 保留为高级池管理入口：预热、离线镜像、确定性 CI fixture、显式 registry 维护。install_skills(...) 仍用于单个本地 Skill 目录的作者开发和 smoke test。

自己编写本地 Skill 时，也应放在完全独立、符合标准结构的目录中。业务代码不要 拼 inline SKILL.md 字符串，也不要使用根目录 skill.yaml 这类 YAML 清单； 应用层只把目录路径交给 executor：

my-skill/
|-- SKILL.md
|-- scripts/
|-- references/
`-- assets/

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

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

install_skills(...) 会把标准本地 Skill 目录复制到本地 registry。安装后的 Skill 根目录仍然直接包含 SKILL.md。Agently 只在安装副本内添加 .agently/ 管理目录。

.agently/skills/release-review/
|-- SKILL.md
|-- scripts/
|-- references/
|-- assets/
`-- .agently/
    |-- install.json
    |-- decision_card.json
    |-- resource_index.json
    `-- checksums.json

.agently/ 文件用于加速路由、检查和资源索引，不是 Skill 能力定义。派生文件缺失或过期时，Agently 会重建，或直接回退读取 SKILL.md。

skill_id 由 SKILL.md frontmatter 里的 name 派生：小写、空白变成 -，只保留 a-z0-9._-。后续调用建议使用安装返回的 contract["skill_id"]。

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

根目录下的 skill.yaml、skill.json、agently.skill.yaml 等非标准清单会被拒绝。scripts/、references/、assets/ 里的同名文件只作为普通资源处理。

选择

用 use_skills(...) 将已安装或远程 Skills 暴露为 route candidates。模型先看到简短 decision cards；只有 Skills route 真正执行时才 materialize 完整 guidance 和资源。

agent = Agently.create_agent("ops-assistant")
agent.use_skills(["release-review"], mode="model_decision")
agent.use_skills([{"source": "anthropics/skills", "subpath": "skills/docx"}], mode="required")

需要检查将会使用哪些 Skills 时，调用 resolve_skills_plan(...)。Required Skills 保持调用方顺序；多个可选候选由模型排序。

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

执行

当任务必须通过 selected Skills 回答时，用 run_skills_task(...)。默认执行策略是 single_shot：Agently 会把 selected Skills 的 SKILL.md guidance、 decision cards、资源摘要和任务放进一次模型请求。声明了 execution: staged 或 allowed-tools 的 Skill 可以走 TriggerFlow 支撑的 staged / react 策略。 当可用 action 存在时，react 会把 tool/action 规划和执行委托给 Agent ActionRuntime，因此 kwargs schema、MCP tools、policy、approval、concurrency 和 Execution Environment 处理仍由 Action 层拥有，而不是由 Skills 重新实现。

execution = await agent.async_run_skills_task(
    "Review this release and give a go/no-go recommendation.",
    skills=["release-review"],
    mode="required",
)

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

output= 使用和 .output(...) 相同的 schema grammar；它就是本次 Skill run 的结构化输出契约，描述 Skill 执行要交付的业务结果形状。 output_format= 才控制承载格式，例如 JSON、flat Markdown、hybrid 或自动选择。 旧的 semantic_outputs= 参数仅作为 Skills 执行的兼容别名保留，并会触发 deprecation warning。

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

显式 Skills 执行也支持 Agent prompt 方法。Skill run 会消费当前 prompt snapshot， 把渲染后的 prompt 文本作为 task，并把 output / output_format slot 映射为 output / output_format：

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")
)

set_agent_prompt(...) 写入的长期 prompt 会被继承并保留给后续轮次； set_request_prompt(...) / quick prompt 写入的本轮 request prompt 会被冻结到这次 Skill run，然后从 pending request 清理。显式传入的 output= 和 output_format= 参数优先于 prompt 推导值。

output_format= 用于选择这次模型响应的输出控制方式。普通 Skill 回答保持默认 "auto"。Auto 是结构规则：扁平且全是字符串字段时选择 "flat_markdown"；顶层 dict 同时包含字符串字段和复杂 list/object 字段时选择 "hybrid"；布尔/数字控制字段、全复杂结构和非 dict 输出选择 "json"。紧凑机器 可读结果、judge、布尔、数字或下游 JSON-only 契约应显式用 "json"。

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="flat_markdown",
)

固定必填字段优先写在 schema 元组第三项：

output = {
    "rules": [
        {
            "rule_id": (str, "Stable rule id", True),
            "passed": (bool, "Whether this rule passed", True),
            "evidence": (str, "Concise evidence; empty string is allowed", False),
        }
    ],
    "passes": (bool, "Overall pass/fail", True),
}

运行时 ensure_keys= 只用于条件路径或运行时才决定的路径。max_retries=3 表示解析失败、必填 key 缺失、严格输出校验失败或自定义 validator 失败时，Agently 最多还会发起三次额外模型尝试。普通遗漏、markdown header 错误、auto format 降级到 JSON 通常能靠重试恢复；但模型持续回显占位符脚手架、用散文填布尔/数字字段、生成畸形嵌套数组、长 prompt 被截断，或需要填很多 rule_results[*].evidence 这类 wildcard 路径时，三次重试后仍可能失败。多规则 model judge 建议显式 output_format="json"，schema 尽量浅，规则过多时拆成多次 judge。

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

• skills.prompt_only.start
• skills.model_stream，包含 path、value、delta、is_complete
• skills.prompt_only.done
• effort="normal" 或 effort="max" 选中内置 planner chain 时，会收到 skills.runtime_chain.*
• 选中多步策略时，还会收到 skills.staged.*、skills.react.* 和 block.* 事件

effort="fast" 使用低开销 single-shot 路径。effort="normal" 固定走完整 preflight -> research -> plan -> execute -> verify -> reflect -> finalize 链路。effort="max" 使用同一链路，但提高 retry 预算，并作为后续 Dynamic Task 升级的挂接点。

需要覆盖内置档位时，可以用 agent.set_settings("effort_presets", {...}) 把调用方 看到的质量/成本档位映射到策略、model key、step budget、retry count 和 artifact inline limit：

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},
})

execution = await agent.async_run_skills_task(
    "Draft a release decision.",
    skills=["release-review"],
    mode="required",
    effort="normal",
)

需要完全自定义行动策略时，可以在 Skills Executor 上注册 effort strategy handler， 再通过 effort= 调用。handler 会拿到 Agent runtime context、选中的 Skills plan、 解析后的 effort config 和 output format；它可以请求模型、通过 context 调用 Action/MCP、发 runtime stream，并返回最终输出。

handler 遵循 SkillsEffortStrategyHandler protocol：

def handler(
    *,
    context: SkillsExecutionContext,
    task: str,
    plan: SkillExecutionPlan,
    output_format: str | None = None,
    effort: str | None = None,
    effort_config: dict | None = None,
) -> Awaitable[Any] | Any: ...

内置 handler 也注册在同一张 strategy 表里：single_shot、runtime_chain、 staged 和 react。可以用 Agently.skills_executor.list_effort_strategies() 查看当前可用策略名。自定义 handler 只有显式传入 replace=True 时才能替换内置策略；否则重名会 fail closed。 内置参考实现位于 agently/builtins/plugins/SkillsExecutor/AgentlySkillsExecutor/modules/effort_strategies/。

async def audit_plus_strategy(*, context, task, plan, effort_config, **_):
    await context.async_emit_runtime_stream({
        "type": "skills.audit_plus.checkpoint",
        "action": "checkpoint",
    })
    return await context.async_request_model(
        prompt={
            "task": task,
            "selected_skills": plan["selected_skills"],
            "policy": effort_config,
        },
        model_key="verifier",
        output_schema={"decision": (str, "go / no-go", True)},
        output_format="json",
    )

Agently.skills_executor.register_effort_strategy(
    "audit_plus",
    audit_plus_strategy,
)

agent.set_settings("effort_presets", {
    "audit_plus": {"strategy": "audit_plus", "custom_budget": 7},
})

execution = await agent.async_run_skills_task(
    "Audit this release.",
    skills=["release-review"],
    mode="required",
    effort="audit_plus",
)

Skills runtime 内部模型调用使用符号阶段 key：planner、research、reason、 executor、verifier、reflector 和 finalizer。如果某个 key 没有在 model_pool 里映射，Agently 会沿用 agent 继承来的模型配置，而不会把这个符号 key 当成 provider model name 发出去。

通过 Agent 自动编排选中 Skills route 时，模型字段流会桥接到稳定路径，例如 skills.model.fields.<field_path>。

安装 Skill 不会自动执行 bundled scripts 或资源。选中的 Skill 如果声明了 mcp、mcpServers、allowed-tools: [Bash] 或 allow-scripts，Skills Executor 会在执行前自动把所需运行时 actions 挂到当前 Agent：MCP 声明走 agent.use_mcp(...)，Bash/scripts 声明走受管的 enable_shell(...) action，并把 工作目录限制在该 Skill 的安装目录。stdio MCP、本地命令和脚本属于高风险能力， 需要 auto_allow=True 或审批 handler；远程 HTTP MCP 不需要这个本地命令审批。

如果选中的 Skill 声明了缺失能力，并且当前没有匹配的 Action/MCP tool，executor 会先做一层保守 fallback：看起来是纯内存计算、解析、校验、转换或格式化的能力， 可以被合成为 execution-scoped 的 Python sandbox action。业务系统、网络、文件、 消息、支付、数据库、浏览器或其他外部副作用能力不会被合成；它们会 fail closed， 返回 capability_missing，直到宿主提供真实 Action、MCP server 或 connector package。

验收样例

examples/agent_auto_orchestration/19_remote_skills_weather_event_ops.py 端到端验证了 4.1.3 的远程连接器路径：业务代码只通过 agent.use_skills(...) 声明公开远程 Skills；免费 weather MCP 服务通过 ActionRuntime 注册；模型生成 MCP action calls 取得真实天气观测；Skills Executor 在命中后懒安装选中的 Skills，并用 effort="normal" 执行完整链路。

配置

Skill 的适用性来自 SKILL.md；Agently 的 .agently/ 文件只是描述性的安装元数据。 多步 Skills 执行应组合 Agently 已有的 TriggerFlow、Action 和 ExecutionEnvironment 边界；人工审批或持久 wait/resume 应通过 TriggerFlow pause_for(...) / continue_with(...)，或 Action / ExecutionEnvironment 审批策略表达，不应通过修改已关闭的 SkillExecution snapshot 来伪装恢复。

框架级 skills.* 配置仍可调整宿主行为，例如普通 prompt 是否披露可选 Skill 候选的完整 guidance。有 plugin defaults 时会先加载 plugin defaults，框架配置 是最终应用级默认值。两层配置都不能替代 SKILL.md 成为 Skill 能力定义。

本地 registry 相关配置应使用公开 Skills Executor 配置 helper：

Agently.skills_executor.configure(
    registry_root="./.agently/skills-dev",
    allowed_trust_levels=["local"],
)

API Summary

• Agently.skills_executor.install_skills(...)
• Agently.skills_executor.install_skills_pack(...)
• Agently.skills_executor.configure(...)
• Agently.skills_executor.inspect_skills(...)
• agent.use_skills(...)
• agent.use_skills_packs(...)
• agent.resolve_skills_plan(...)
• agent.run_skills_task(...)

SkillContract 描述已安装的标准 Skill、Agently 安装元数据、decision card、 资源索引和 checksums，不包含框架自创的 stage 声明。