docs: update skills extension to support .agents/skills directories#6199
docs: update skills extension to support .agents/skills directories#6199michaelneale merged 2 commits intoblock:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds support for agent-agnostic skill directories (.agents/skills/ at both project and global levels) to make skills portable across different AI coding agents. The changes update both documentation and code to recognize these new directories alongside existing goose-specific and Claude-compatible paths.
Key changes:
- Adds
.agents/skills/(project-level) and~/.config/agents/skills/(global) to supported skill directories - Documents all six skill directory locations in priority order
- Updates Skills extension description to be more generic
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
documentation/docs/mcp/skills-mcp.md |
New documentation page explaining the Skills extension with examples using the new .agents/skills/ paths |
documentation/docs/guides/context-engineering/using-skills.md |
New guide documenting all six skill directory locations in priority order with detailed usage examples |
crates/goose/src/agents/skills_extension.rs |
Adds the two new .agents/skills/ directory paths to the skill discovery logic |
crates/goose/src/agents/extension.rs |
Updates Skills extension description to be more generic and avoid listing specific directories |
joahg
force-pushed
the
joah/update-skills-docs
branch
from
41487ae to
e86ad95
Compare
|
Thanks @joahg ! Is the agents support already in a released version? >> Never mind, I see it's in v1.18.0. Also pinging @blackgirlbytes who had wanted Claude compatibility to be very visible |
| The Skills extension loads *skills* — reusable sets of instructions that teach goose how to perform specific tasks or follow particular workflows. | ||
|
|
||
| goose automatically discovers skills at startup and uses them when relevant to your request. goose skills are compatible with Claude Desktop's skill format, so skills you create for one tool work with both. To learn about creating skills and how goose uses them, see [Using Skills](/docs/guides/context-engineering/using-skills). | ||
| goose automatically discovers skills at startup and uses them when relevant to your request. goose loads skills from `.agents/skills/` in your project directory and `~/.config/agents/skills/` globally, making skills portable across different AI coding agents. To learn about creating skills and how goose uses them, see [Using Skills](/docs/guides/context-engineering/using-skills). |
There was a problem hiding this comment.
This sentence only mentions 2 of the 6 skill directories that goose actually checks. While it highlights the new agent-agnostic paths, it could mislead users into thinking these are the only directories supported. Consider mentioning that goose checks multiple directories for compatibility, or add "including" before the specific paths to clarify these are examples.
| goose automatically discovers skills at startup and uses them when relevant to your request. goose loads skills from `.agents/skills/` in your project directory and `~/.config/agents/skills/` globally, making skills portable across different AI coding agents. To learn about creating skills and how goose uses them, see [Using Skills](/docs/guides/context-engineering/using-skills). | |
| goose automatically discovers skills at startup and uses them when relevant to your request. For compatibility with different AI coding agents, goose checks multiple standard locations for skills, including `.agents/skills/` in your project directory and `~/.config/agents/skills/` globally, making skills portable across different AI coding agents. To learn about creating skills and how goose uses them, see [Using Skills](/docs/guides/context-engineering/using-skills). |
| <GooseBuiltinInstaller | ||
| extensionName="Skills" | ||
| description="Load and use skills from the .claude/skills or .goose/skills directories" | ||
| description="Load and use skills from the .agents/skills directory" |
There was a problem hiding this comment.
The description changed from mentioning multiple directories (".claude/skills or .goose/skills") to only ".agents/skills directory" (singular). This is less accurate since goose actually loads skills from 6 different directories. Consider using "Load and use skills from .agents/skills, .goose/skills, and .claude/skills directories" to better reflect the actual behavior.
| description="Load and use skills from the .agents/skills directory" | |
| description="Load and use skills from .agents/skills, .goose/skills, and .claude/skills directories" |
michaelneale
left a comment
michaelneale
left a comment
There was a problem hiding this comment.
thanks @joahg not sure why DCO check now failing but if you could sign them if needed, lets get this in .
| ::: | ||
|
|
||
| ## Claude Compatibility | ||
| ## Skill Locations |
There was a problem hiding this comment.
Hmm I don't think we should remove the mention that this is compatible with Claude Code. This is a pull for a lot of people to use skills with goose and helps with association..like "ohhhh, I could use this here too"
I'm okay if we update this heading to say Skills location but I think we should add a call out or admonition that says something like
::: note Claude Code Compatibility
goose Skills are compatible with Claude Code and other agents that support Agent Skills
Describe the paths .claude/skills or whatever the new path is
:::
obviously, don't write this verbatim, but that may be a possible direction we want to go cc: @dianed-square
There was a problem hiding this comment.
Diane will approve to merge this and we will add the note above as a fast follow
…block#6190) Signed-off-by: Adrian Cole <adrian@tetrate.io> Signed-off-by: Joah Gerstenberg <joah@squareup.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019b37b4-e1cd-7194-ae9f-4c277e47ffb5 Co-authored-by: Amp <amp@ampcode.com> Signed-off-by: Joah Gerstenberg <joah@squareup.com>
joahg
force-pushed
the
joah/update-skills-docs
branch
from
e5540c9 to
8007d66
Compare
…lock#6199) Signed-off-by: Adrian Cole <adrian@tetrate.io> Signed-off-by: Joah Gerstenberg <joah@squareup.com> Co-authored-by: Adrian Cole <64215+codefromthecrypt@users.noreply.github.com> Co-authored-by: Amp <amp@ampcode.com>
* main: (155 commits) remove Tool Selection Strategy preview (#6250) fix(cli): correct bash syntax in terminal integration functions (#6181) fix : opening a session to view it modifies session history order in desktop (#6156) test: fix recipe and audio tests to avoid side effects (#6231) chore: Update gemini versions in test_providers.sh (#6246) feat: option to stream json - jsonl really (#6228) feat: add mcp app renderer (#6095) docs: update skills extension to support .agents/skills directories (#6199) Add YouTube short to Chrome DevTools MCP tutorial (#6244) docs: Caveats for privacy information in logs documentation (#6218) move goose issue solver to opus (#6233) feat: improved UX for tool calls via execute_code (#6205) Blog: Code Mode Doesn't Replace MCP (#6227) fix: prevent keychain requests during cargo test (#6219) test: fix test_max_turns_limit slow execution and wrong message type (#6221) Skills vs MCP blog (#6220) Add blog post: Does Your AI Agent Need a Plan? (#6209) fix(ui): enable MCP UI to send a prompt message when an element is clicked (#6207) docs: param option for recipe deeplink/open (#6206) docs: edit in place or fork session (#6203) ...
5 participants
Updates the skills extension documentation to include the new agent-agnostic skill directories:
.agents/skills/(project-level)~/.config/agents/skills/(global)These paths make skills portable across different AI coding agents. The documentation now lists all six supported directories in priority order.