Goose Agent Skills 完整指南：为 goose 打造可复用技能、从创建到加载的实战手册

• 人工智能
• 大模型
• AI Agent
• AI 应用
• 本地部署
• MCP Clients
• MCP 服务
• 工具调用

导读

本篇指南围绕 goose 内置的Agent Skills（技能）平台扩展展开，讲解如何用一套可复用的指令与配套资源（脚本、模板、配置文件）教会 goose 完成特定任务，覆盖内置技能、技能存放位置、SKILL.md文件结构、插件技能、配套文件与最佳实践。读完本文，你将掌握创建SKILL.md、在会话中列出与加载技能、复用内置web-search、为技能附带参数与配套文件，以及通过插件分发技能的全套能力。相关源码集中在 crates/goose/src/skills 与 crates/goose-cli/src/commands/skills.rs，可对照阅读。

什么是 Agent Skills

Skills 是可复用的指令与资源集合，用来教会 goose 如何执行特定任务。一个技能既可以简单到一张清单，也可以复杂到包含领域知识的完整工作流，还能携带脚本、模板等支持性文件。典型使用场景包括部署流程、代码评审清单、API 集成指南等。

该功能基于内置的Skills 平台扩展，默认启用。在 crates/goose/src/agents/platform_extensions/mod.rs 中可以看到它被注册为default_enabled: true的平台扩展，其 MCP 客户端由crate::skills::SkillsClient::default()提供，扩展描述为"从文件系统与内置源发现并提供技能指令"。

技能如何在会话中生效

会话启动：名称与描述注入指令

当一次会话启动时，goose 会把发现到的技能名称和描述添加到自己的系统指令中。这一逻辑在 crates/goose/src/skills/client.rs 的get_instructions方法里实现：它调用discover_skills汇总所有技能，按名称排序后拼出类似下面的一段指令：

You have these skills at your disposal, when it is clear they can help you solve a problem or you are asked to use them: • web-search - Search the web and extract page content using DuckDuckGo ...

也就是说，模型在每一轮都"知道有哪些技能可用"，但完整指令内容并不会一次性全部注入——技能正文按需加载。

会话中：按需加载完整指令

在会话进行中，goose 会在以下情形加载某个技能的完整指令：

• 你的请求明显匹配某个技能的目的；
• 你明确要求使用某个技能，例如：
  • "Use the code-review skill to review this PR"
  • "Follow the new-service skill to set up the auth service"
  • "Apply the deployment skill"

底层机制是一个名为load_skill的工具（同样定义在 client.rs），它的参数 schema 包含两个字段：name（技能名，或"skill-name/path"形式用于加载配套文件）与可选的args（加载技能时提供的参数）。加载后，技能正文会以# Loaded Skill: <name> (<source_type>)的格式写入上下文。

列出与加载技能的命令

你可以直接向 goose 询问有哪些技能可用，也可以运行goose skills list，或者使用 CLI 的/skills命令列出技能并加载一个或多个：

/skills code-review edge-case-finder

• 不带参数时/skills等价于列出可用技能（InputResult::ListSkills）；
• 带参数时按空白拆分技能名并逐个加载（InputResult::LoadSkills(names)），见 crates/goose-cli/src/session/input.rs。

goose skills list子命令在 crates/goose-cli/src/commands/skills.rs 中实现，它以当前工作目录为基准调用list_installed_skills，按名称排序后输出一个表格，包含Name、Description、Description tokens、Content tokens、Location五列——其中 token 数用create_token_counter统计，方便你评估每个技能对上下文的占用；会话内的/skills补全则由 crates/goose-cli/src/session/completion.rs 提供技能名补全。

Claude 兼容性

goose skills 与 Claude Desktop 以及其他支持 Agent Skills 的智能体兼容，遵循业界通用的 Agent Skills 规范。从源码看，crates/goose/src/skills/mod.rs 中的SkillFrontmatter结构即按 agentskills.io 规范解析 frontmatter，name、description为保留字段，其余自定义元数据统一放入嵌套的metadata映射中，避免与保留字段冲突。

内置技能

goose 随包内置了一个开箱即用、无需任何安装的技能：

内置技能以include_dir!方式编译进二进制，源码位于 crates/goose/src/skills/builtins/web_search.md，注册逻辑见 crates/goose/src/skills/builtin.rs；发现时其路径标记为builtin://skills/<name>（见 crates/goose/src/skills/mod.rs）。

web-search 实战用法

web-search技能要求本机安装uv（curl -LsSf https://astral.sh/uv/install.sh | sh），默认的 DuckDuckGo 路径不需要任何 API key。

默认方式——DuckDuckGo（无需 API key）：

uvx ddgs text -q "your query here" -m 5

Tavily（结果更丰富，需要设置TAVILY_API_KEY）：

uvx --from tavily-python python -c " import os from tavily import TavilyClient r = TavilyClient(os.environ['TAVILY_API_KEY']).search('your query here', max_results=5) for res in r['results']: print(res['url']) print(res['content']) print() "

SearXNG（自托管，需要设置SEARXNG_URL）：

curl -sG --data-urlencode "q=your query here" --data "format=json" "${SEARXNG_URL}/search" | python3 -c " import json, sys data = json.load(sys.stdin) for r in data.get('results', [])[:5]: print(r['url']) print(r.get('content','')) print() "

引擎选择优先级：设置TAVILY_API_KEY时用 Tavily，否则设置SEARXNG_URL时用 SearXNG，再否则回退到 DuckDuckGo。

提取页面内容（将 HTML 转为纯文本）：

url="https://example.com" tmpfile=$(mktemp /tmp/page-XXXXXX) curl -sL --max-time 15 -A "Mozilla/5.0" "$url" | uvx html2text --ignore-links > "$tmpfile" 2>/dev/null wc -c "$tmpfile" head -c 15000 "$tmpfile"

如果页面超过 15000 字符，同时展示头部与尾部，让用户决定是否通读全文：

echo "--- HEAD ---" head -c 7500 "$tmpfile" echo "" echo "--- TAIL ---" tail -c 7500 "$tmpfile" echo "" echo "(Full content saved to $tmpfile)"

使用规则：搜索查询务必加引号以避免 shell 分词；抓取时遵守robots.txt，不要对同一主机高频请求；绝不向外部 URL 发送认证 cookie 或会话令牌；若页面返回登录墙或 CAPTCHA，报告 URL 后停止，不要尝试绕过。

安装 browser-use 技能

如需浏览器自动化（导航页面、点击、填写表单、截图），可安装上游维护的 browser-use 技能：

browser-use skill install

这会带来 browser-use 项目最新、最完整的技能，包括远程浏览器支持、AX-tree 元素选择策略与录制工具。

技能存放位置

技能可以存放在全局、项目级或已安装的插件中：

1. ~/.agents/skills/—— 全局技能，所有会话可用；
2. .agents/skills/—— 项目级技能，仅作用于当前项目；
3. ~/.agents/plugins/<plugin-name>/—— 由已安装的插件提供的技能。

将SKILL.md文件放入一个具名子目录即可。例如一个名为code-review的全局技能，其文件位于~/.agents/skills/code-review/SKILL.md。

向后兼容：goose 也会从.goose/skills/、.claude/skills/、~/.claude/skills/以及平台特定的配置目录发现技能，但agents/skills/是推荐标准。

从源码看，crates/goose/src/skills/mod.rs 的all_skill_dirs_with_config完整枚举了发现顺序：项目目录（.agents/skills、.goose/skills、.claude/skills）在前，随后是项目插件技能，然后是全局目录（~/.agents/skills、配置目录skills、~/.claude/skills、~/.config/agents/skills），最后是用户插件技能；discover_skills按此顺序去重合并，并跳过.git、.hg、.svn目录（见 mod.rs）。同一名称的技能，项目级优先于全局级（对应测试project_plugin_skill_precedes_global_skill_with_same_name验证了这一优先级）。

创建技能

当某个工作流需要多步骤、专业知识或配套文件且会被重复执行时，就该为它创建一个技能。

技能文件结构

每个技能拥有独立目录，内含一个SKILL.md文件：

~/.agents/skills/ └── code-review/ └── SKILL.md

SKILL.md要求以YAML frontmatter开头，声明name与description，其后是技能正文：

--- name: code-review description: Comprehensive code review checklist for pull requests --- # Code Review Checklist When reviewing code, check each of these areas: ## Functionality - [ ] Code does what the PR description claims - [ ] Edge cases are handled - [ ] Error handling is appropriate ## Code Quality - [ ] Follows project style guide - [ ] No hardcoded values that should be configurable - [ ] Functions are focused and well-named ## Testing - [ ] New functionality has tests - [ ] Tests are meaningful, not just for coverage - [ ] Existing tests still pass ## Security - [ ] No credentials or secrets in code - [ ] User input is validated - [ ] SQL queries are parameterized

名字与 frontmatter 校验规则

从源码可确认以下硬性规则（crates/goose/src/skills/mod.rs 的validate_skill_name，以及parse_skill_content）：

• 技能名不能为空，长度最多64 字符；
• 只能包含小写字母、数字和连字符（-），不能以连字符开头或结尾；
• 缺失name或名称包含/的技能会被跳过并记录警告（mod.rs）；
• description会随会话启动注入系统指令，因此务必写清楚技能用途，便于模型判断何时加载。

技能参数（args）

load_skill工具支持可选的args参数，技能正文中可以使用占位符接收参数。实现位于 crates/goose/src/skills/arguments.rs：

• $ARGUMENTS—— 替换为全部原始参数；
• $1、$2…… —— 位置参数（从 1 开始索引）；
• $ARGUMENTS[0]、$ARGUMENTS[1]…… —— 按从 0 开始的索引取参数；
• $name—— 具名参数，对应 frontmattermetadata中声明的arguments列表（声明后按位置映射）；未声明的$name保持字面量；
• 若技能正文不含任何占位符，参数会以ARGUMENTS: <raw>标记追加在正文末尾；
• 引号可把多个词聚合成一个 token（"57 Collins"是一个整体），Windows 反斜杠路径也能被正确保留。

对应单元测试见 crates/goose/src/skills/arguments.rs，例如Migrate $component from $from to $to配合component/from/to声明与参数Button old-lib new-lib会渲染为Migrate Button from old-lib to new-lib.。

来自插件的技能

技能也可以来自已安装的插件。插件提供的技能在会话启动时同样会被发现，行为与其他技能一致。对于 Open Plugins，技能名会以插件名作为命名空间，例如my-plugin:review；显式加载插件技能时要使用完整名称。

插件技能通过enabled_plugin_skill_dirs_with_config纳入发现流程（crates/goose/src/skills/mod.rs）。插件清单plugin.json可通过skills.paths声明自定义技能目录、skills.exclusive控制是否排除默认技能根目录，相关测试（如exclusive_project_plugin_manifest_omits_default_skill_root）在 crates/goose/src/skills/mod.rs 中验证了这些行为。插件技能默认只读（writable: false），不会被create_source/update_source/delete_source等 CRUD 操作意外修改。

配套文件（Supporting Files）

技能可以携带脚本、模板、配置文件等配套文件，放入技能目录即可：

~/.agents/skills/ └── api-setup/ ├── SKILL.md ├── setup.sh └── templates/ └── config.template.json

goose 加载技能时会一并看到这些配套文件，并通过 Developer 扩展（developer-mcp 文档）的文件工具访问它们。底层通过load_skill(name: "skill-name/path")加载配套文件（见 client.rs），加载后的内容以# Loaded: <skill-name/path>包裹写入上下文。

路径与安全细节：配套文件的相对路径以技能目录为基准解析，而 shell 工具运行在会话工作目录，所以运行配套脚本前需使用解析后的绝对路径或先cd进技能目录（见 crates/goose/src/skills/mod.rs 生成的加载上下文）。配套文件读取受max_tool_response_size字符数限制，且路径必须始终停留在技能目录内——..、绝对路径、符号链接祖先都会被拒绝（crates/goose/src/skills/supporting_files.rs 通过openat逐步打开目录句柄实现反符号链接、反目录穿越，并有rejects_symlinked_ancestor、stays_in_opened_ancestor_after_symlink_swap等测试佐证）。

带配套文件的示例技能

SKILL.md：

--- name: api-setup description: Set up API integration with configuration and helper scripts --- # API Setup This skill helps you set up a new API integration with our standard configuration. ## Steps 1. Run `setup.sh <api-name>` to create the integration directory 2. Copy `templates/config.template.json` to your integration directory 3. Update the config with your API credentials 4. Test the connection ## Configuration The config template includes: - `api_key`: Your API key (get from the provider's dashboard) - `endpoint`: API endpoint URL - `timeout`: Request timeout in seconds (default: 30) ## Verification After setup, verify: - [ ] Config file is valid JSON - [ ] API key is set and not a placeholder - [ ] Test connection succeeds

setup.sh：

#!/bin/bash API_NAME=$1 mkdir -p "integrations/$API_NAME" cp templates/config.template.json "integrations/$API_NAME/config.json" echo "Created integration directory for $API_NAME" echo "Edit integrations/$API_NAME/config.json with your credentials"

templates/config.template.json：

{ "api_key": "YOUR_API_KEY_HERE", "endpoint": "https://api.example.com/v1", "timeout": 30, "retry_attempts": 3 }

常见场景示例

部署工作流

--- name: production-deploy description: Safe deployment procedure for production environment --- # Production Deployment ## Pre-deployment 1. Ensure all tests pass 2. Get approval from at least 2 reviewers 3. Notify #deployments channel ## Deploy 1. Create release branch from main 2. Run `npm run build:prod` 3. Deploy to staging, verify, then production 4. Monitor error rates for 30 minutes ## Rollback If error rate exceeds 1%: 1. Revert to previous deployment 2. Notify #incidents channel 3. Create incident report

测试策略

--- name: testing-strategy description: Guidelines for writing effective tests in this project --- # Testing Guidelines ## Unit Tests - Test one thing per test - Use descriptive test names: `test_user_creation_fails_with_invalid_email` - Mock external dependencies ## Integration Tests - Test API endpoints with realistic data - Verify database state changes - Clean up test data after each test ## Running Tests - `npm test` — Run all tests - `npm test:unit` — Unit tests only - `npm test:integration` — Integration tests (requires database)

API 集成指南

--- name: square-integration description: How to integrate with our Square account --- # Square Integration ## Authentication - Test key: Use `SQUARE_TEST_KEY` from `.env.test` - Production key: In 1Password under "Square Production" ## Common Operations ### Create a customer ```javascript const customer = await squareup.customers.create({ email: user.email, metadata: { userId: user.id } }); ``` ### Handle webhooks Always verify webhook signatures. See `src/webhooks/square.js` for our handler pattern. ## Error Handling - `card_declined`: Show user-friendly message, suggest different payment method - `rate_limit`: Implement exponential backoff - `invalid_request`: Log full error, likely a bug in our code

最佳实践

• 保持技能聚焦—— 一个技能对应一个工作流或领域。技能变长时，考虑拆分。
• 为清晰而写—— 技能是写给 goose 的指令。使用清晰、直接的语言和编号步骤。
• 包含验证步骤—— 帮助 goose 确认工作流已成功完成。

此外，goose 还提供了其他支持复用能力的机制，可与之配合：

• .goosehints：适合承载通用偏好、项目上下文与重复性指令（如"始终使用 TypeScript"）；
• recipes（会话配方）：可共享的配置包，将指令、提示词与设置打包在一起。

三者的取舍可概括为：技能解决"如何执行某个具体任务"，goosehints 解决"始终要遵守的偏好"，recipes 解决"整套会话的启动配置"。官方博客 Agent Skills vs MCP 还进一步对比了技能与 MCP 的差异，可作为延伸阅读。

小结

Agent Skills 是 goose 实现任务复用与工作流沉淀的核心机制：内置的web-search开箱即用，~/.agents/skills/与.agents/skills/提供了全局/项目两级自定义能力，SKILL.md的 frontmatter + 正文结构简单而规范，配套文件与参数机制让技能具备完整的执行能力，插件则让技能可以被安装、共享与更新。结合 crates/goose/src/skills 下的源码与测试，你可以放心地把团队的部署清单、代码评审清单、API 集成流程写成技能，让 goose 在合适的时机自动加载并执行。

• 人工智能
• 大模型
• AI Agent
• AI 应用
• 本地部署
• MCP Clients
• MCP 服务
• 工具调用