IronClaw Skills 系统深度指南：SKILL.md 格式、信任模型与确定性激活管线

IronClaw Skills 系统深度指南SKILL.md 格式、信任模型与确定性激活管线【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw本指南系统讲解 IronClawAgent OS中 Skills 系统的完整工作机制SKILL.md 如何以 YAML frontmatter 元数据 Markdown 正文的形式向 LLM 注入领域指令Trusted / Installed 两级信任模型如何约束工具权限以及 Gating → Scoring → Budget → Attenuation 四阶段选择管线背后的确定性计分逻辑。读完本文你将能够为 IronClaw 编写可被自动激活的技能、正确配置激活条件与预算上限并理解从技能发现、评分到上下文注入的完整链路。什么是 Skills System在 IronClaw 中SKILL.md 文件将领域专属指令扩展进 Agent 的提示词prompt。每个技能skill由两部分组成YAML frontmatter 元数据块声明名称、版本、激活条件activation criteria与所需工具required toolsMarkdown 正文技能指令本体会被注入 LLM 上下文。系统定位由 .claude/rules/skills.md 定义其作用域覆盖crates/domains/ironclaw_skills/**、crates/extensions/ironclaw_extension_host/src/bundled_skills.rs与仓库根目录的skills/**仓库内已内置 coding、commit、delegation、security-review 等 15 个技能目录见 skills/。从源码结构看技能从磁盘到上下文的完整旅程由 crates/domains/ironclaw_skills/ 与 crates/loop/ironclaw_loop_host/src/skill_activation/activation.rs 共同完成前者负责解析、校验与确定性预筛后者负责按回合turn把选中的技能正文渲染进模型上下文。信任模型两级信任决定内容暴露与工具上限IronClaw 将技能按来源划分为两个信任等级核心区别在于内容暴露content exposure与工具访问tool access信任等级来源工具访问Trusted用户放置于~/.ironclaw/skills/或工作区skills/目录Agent 可用的全部工具Installed从 ClawHub 注册表或 HTTPS 技能 URL 下载~/.ironclaw/installed_skills/或在 Reborn 作用域技能存储中记录 URL 来源元数据仅只读工具无 shell、无文件写入、无 HTTP在 crates/domains/ironclaw_skills/src/types.rs 中SkillTrust枚举通过判别值定义顺序Installed 0Trusted 1。源码注释明确警告Ord派生自判别值安全模型依赖Installed Trusted的大小关系不得重排变体顺序。SkillSource则区分四种加载位置Workspace工作区skills/、User用户目录~/.ironclaw/skills/、Installed注册表安装目录~/.ironclaw/installed_skills/与Bundled随应用内置。值得强调的是信任等级直接决定模型能看到什么ironclaw_loop_contracts::skill_context::SkillTrustLevel依据信任等级决定模型是看到技能的完整 prompt 正文还是仅看到安全描述而真正的工具权限归ironclaw_authorization/ironclaw_capabilities所有见 types.rs 中的类型注释。选择管线末端的Attenuation衰减阶段会取当前激活技能中的最低信任等级作为工具上限Installed 技能因此自动失去危险工具。SKILL.md 格式详解frontmatter 元数据与正文标准结构示例--- name: my-skill version: 0.1.0 description: Does something useful activation: patterns: - deploy to.*production keywords: - deployment exclude_keywords: - rollback tags: - devops max_context_tokens: 2000 requires: bins: [docker, kubectl] env: [KUBECONFIG] --- # Skill instructions here...关键字段与解析约束name/version/description技能标识与人类可读描述version缺省为0.0.0见 types.rs 中default_version。activation激活条件包含keywords精确/子串匹配、patterns正则、exclude_keywords否决词、tags宽泛分类标签、max_context_tokens默认 2000以及setup_marker一次性安装标记见下文。requires加载门控输入支持binsPATH 上的可执行文件、env环境变量、config配置文件路径与skills伴生技能。重要兼容性说明仅支持顶层的requires:块。历史遗留的嵌套写法metadata.openclaw.requires不被支持当前解析器会直接忽略因此旧的外部技能必须显式迁移而不能依赖静默兼容。静默截断上限Silent truncation capsenforce_limits见 types.rs在加载时对激活元数据强制实施以下硬性上限超出的部分静默丢弃、不报错字段上限说明keywordsMAX_KEYWORDS_PER_SKILL 20同时过滤长度 3 的短词exclude_keywordsMAX_KEYWORDS_PER_SKILL 20同上patternsMAX_PATTERNS_PER_SKILL 5—tagsMAX_TAGS_PER_SKILL 10同时过滤长度 3 的短标签requires.skillsMAX_REQUIRED_SKILLS_PER_MANIFEST 10防止恶意清单令链式安装队列无界增长setup_markerMAX_SETUP_MARKER_LENGTH 256字节含..路径穿越或超长时直接置为None源码对短词过滤的动机有明确注释长度不足 3 的 token如 a、is匹配过宽会被用来操纵评分系统。此外正则编译在加载期完成且对编译后的正则状态施加 64 KiB 的大小限制MAX_REGEX_SIZE以防范病态正则导致的 ReDoS无效正则会打 warning 并跳过LoadedSkill::compile_patterns。技能 prompt 文件本身的上限为MAX_PROMPT_FILE_SIZE 64 KiB。凭证声明credentials技能可在 frontmatter 中声明 API 凭证需求SkillCredentialSpec系统据此注册 host→凭证映射并管理 OAuth 流程无需 WASM 模块介入。凭证值永不进入 LLM 上下文加载时只解析元数据。支持的位置类型包括Bearer、BasicAuthusername、Header自定义头 可选前缀与QueryParamOAuth 刷新策略支持standard/reauthorize_only/custom见 types.rs 的SkillCredentialLocation与ProviderRefreshStrategy。选择管线Gating → Scoring → Budget → Attenuation技能激活是确定性deterministic的——不依赖 LLM 参与预筛防止已加载技能影响哪些技能被加载的循环操纵见 selector.rs 模块注释。整条管线分四步1. Gating门控检查技能声明的requires.bins/requires.env/requires.config是否满足前置条件缺失的技能被直接跳过。实现位于 gating.rsbins通过whichUnix/whereWindows探测env检查环境变量是否已设置config检查路径是否存在。异步封装check_requirements会把阻塞的which调用通过spawn_blocking卸载且当三项都为空时立即返回通过常见场景避免每次技能加载都起子进程。requires.skills属咨询性元数据不参与门控——缺失伴生技能不会阻止父技能加载。2. Scoring确定性计分计分规则定义于 selector.rs 的score_skill对用户消息做小写化后逐技能评分信号分值上限关键词精确匹配整词按空白切分10 分30 分关键词子串匹配5 分30 分标签匹配子串3 分15 分正则模式匹配20 分40 分exclude_keywords命中一票否决总分归 0—上限设计防止关键词填充keyword stuffing操纵评分即使一个技能声明满 20 个关键词最多也只能拿 30 分正则即使命中全部 5 条理论上 100 分也被压到 40 分无法压过关键词标签组合。此外正则匹配仅对 ≤ 64 KiB 的消息执行MAX_REGEX_MATCH_MESSAGE_BYTES避免热路径上的 O(n) 开销。正则激活开关patterns正则评分受配置项[skills] regex_activation_enabled门控默认true配置为false时正则贡献 0 分只有关键词/标签/显式提及能选中技能。该配置由SkillsSection定义于 crates/app/ironclaw_config/src/config_file.rs没有对应的环境变量。配置文件中以regex_activation_enabled false形式使用见同文件测试样例。显式提及explicit mention用户在消息任意位置写/skill-name或$name可强制激活技能。extract_skill_mentions会把消息中的/github之类提及替换为技能描述如 GitHub API使句子对 LLM 仍然通顺同时将技能强制纳入选择。该解析仅在/位于消息开头或前导空白/标点之后is_skill_mention_boundary时生效技能名接受[a-zA-Z0-9._-]字符集。激活策略回退默认策略为CriteriaOnly纯条件计分。ActivationStrategy::NameAndDescription允许在条件计分为 0 时回退到技能name/description的整词匹配名称命中 8 分、描述命中 2 分、回退总上限 20 分见 activation_strategy.rs。该策略的动机是实测 SkillsBench 31 项任务子集中Agent 为自己编写的技能0/30 携带activation块纯条件策略下这些技能永远无法再次被选中回退策略让 Agent 自产技能仅凭名称/描述即可被复用同时刻意让显式策划的关键词永远压过名称碰撞NAME_WORD_SCORE 8 10。策略通过[skills] activation绑定解析如name_and_description、disabled、ext:extension_id。3. Budget预算按分数从高到低选择技能受两个约束限制候选数量上限DEFAULT_MAX_ACTIVE_SKILLS 8以及上下文 token 预算DEFAULT_MAX_SKILL_CONTEXT_TOKENS 4000。二者均定义于 crates/loop/ironclaw_loop_host/src/skill_activation/activation.rs旧的SKILLS_MAX_TOKENS环境变量已无任何代码读取可通过SkillActivationSelectorConfig::set_max_context_tokens等方法覆盖。token 成本估算skill_token_cost优先采用技能声明的max_context_tokens但当正文实际估算约 0.25 token/字节超过声明值的 2 倍时会改用实际估算并告警max_context_tokens: 0也会被强制按 1 token 计费防止绕过预算。链式加载chain-loading被选中技能的requires.skills伴生技能会随父技能一并拉入若可用绕过评分过滤但共享同一预算并受候选上限约束链式加载是非传递的深度 1伴生技能不会再加载自己的伴生技能保证行为可预测。预算不足或 setup 已完成的伴生会被跳过并给出说明性 note。一次性安装标记setup_markeractivation.setup_marker将技能门控在工作区 setup-marker 文件是否存在上。*-setup技能家族首次引导时激活并写入标记文件此后该技能不再参与激活预算竞争要重新触发删除工作区中的标记文件即可典型标记如commitments/.developer-setup-complete。4. Attenuation衰减取所有激活技能中的最低信任等级作为本回合工具上限Installed 技能因此自动降级为只读工具集。技能管理工具集Skill ToolsIronClaw 为 Agent 提供一组内置工具来发现、安装与管理技能工具作用skill_list列出所有已发现技能含信任等级与状态skill_search在 ClawHub 注册表搜索可用技能skill_install从原始 SKILL.md 内容或 ClawHub 安装技能skill_install_url从 HTTPS 原始 SKILL.md、ZIP 包或受支持的 GitHub 仓库/目录 URL 拉取并安装skill_remove移除已安装技能需要说明的是ClawHub 是文档中提到的技能注册表概念对应~/.ironclaw/installed_skills/安装目录HTTPS URL 安装路径会在 Reborn 作用域技能存储中记录来源元数据用于溯源与信任判定。仓库内技能实践与验证内置技能集仓库根目录 skills/ 提供 15 个开箱即用的技能目录覆盖编码coding、提交commit、委托delegation、安全审查security-review、QA 审查qa-review、决策记录decision-capture等 Agent 工作流每个目录均以SKILL.md为核心文件可作为编写自定义技能的参照范例。测试与回归保障crates/domains/ironclaw_skills/tests/routing_corpus.rs 与fixtures/routing_corpus.json基于真实语料验证技能路由的正确性防止一个技能被另一个无关技能抢占对应文档所述跨技能干扰问题。crates/domains/ironclaw_skills/tests/host_picks_wrong_skills.rs回归宿主选中错误技能的失败模式。crates/domains/ironclaw_skills/tests/agent_authored_skills_pass_the_lint.rs确保 Agent 自产技能能通过目录规范检查。crates/domains/ironclaw_skills/tests/catalog_lint.rs对技能目录整体做静态检查。单元测试覆盖计分上限test_keyword_score_capped、test_regex_score_capped、exclude_keywords否决优先级test_exclude_keyword_veto_wins_over_positive_match、无效正则优雅处理test_invalid_regex_handled_gracefully等关键边界。编写与调优实践建议控制激活元数据规模关键词 ≤ 20、正则 ≤ 5、标签 ≤ 10超出的触发条件会被静默丢弃——写了但不存在是最隐蔽的失效方式。善用exclude_keywords防止串扰例如技能以write为关键词时用redirect、route等词否决路由类场景避免跨技能误触发。声明真实的requires缺失的二进制/环境变量会导致技能在门控阶段被跳过requires.skills用于声明与哪些伴生技能配合。为一次性引导技能设置setup_marker引导完成后不再占用每回合的 4000 token 预算。为自产技能补充description若无法或不愿编写激活条件可选用NameAndDescription激活策略让技能仅凭名称与描述被选中否则纯条件策略下没有activation块的技能将永远无法自动激活。解析器行为变更须同步文档仓库规范要求当解析行为变化时在同一 PR 内更新.claude/rules/skills.md见.claude/rules/guidance-maintenance.md规则 7保持代码—文档—测试三者一致。总结IronClaw 的 Skills 系统是一个以确定性为核心的技能注入框架两级信任模型在内容暴露与工具权限上建立安全边界frontmatter 解析以硬性上限与 sanitize 抵御恶意清单四阶段选择管线Gating → Scoring → Budget → Attenuation保证选择过程可预测、可审计、可回归。无论是编写一个新技能、迁移历史技能的requires写法还是调优激活预算与正则开关本文给出的字段说明、计分规则与源码路径都可作为直接依据。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考