feat: Add built-in skill for goose documentation reference #6534

lifeizhou-ap · 2026-01-16T08:11:31Z

Summary

Create a built-in skill to discover docs for user when they using goose feature. For example, help user to create a recipe with accurate recipe schema, understand how goose feature works, ....

Changes

Created a built-in skill that instruct the agent to find the relevant documentation page starting from goose-doc-map.md page to help user perform tasks

TODO
Will change the doc url after this PR #6598 is merged

Type of Change

AI Assistance

This PR was created or reviewed with AI assistance

Testing

Manual testing

github-actions · 2026-01-16T08:14:16Z

PR Preview Action v1.6.3
🚀 View preview at https://block.github.io/goose/pr-preview/pr-6534/
Built to branch `gh-pages` at 2026-01-21 01:11 UTC. Preview will be ready when the GitHub Pages deployment is complete.

This reverts commit a0d92a2.

This reverts commit d13e888.

Copilot

Pull request overview

This PR introduces a built-in skills system to goose, enabling the agent to reference documentation dynamically. The primary addition is a goose-doc-guide skill that instructs the agent to fetch relevant documentation from a local server when helping users with goose-specific tasks like creating recipes or configuring extensions.

Changes:

Added built-in skills infrastructure using compile-time file embedding
Implemented priority-based skill loading (built-in skills are loaded first, then filesystem skills which can override)
Created the goose-doc-guide skill with detailed instructions for documentation-based assistance

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
crates/goose/src/agents/mod.rs	Adds builtin_skills module to the agents module hierarchy
crates/goose/src/agents/builtin_skills/mod.rs	Implements built-in skill discovery using include_dir to embed .md files at compile time
crates/goose/src/agents/builtin_skills/goose_doc_guide.md	Defines the documentation reference skill with instructions for fetching and using goose docs
crates/goose/src/agents/skills_extension.rs	Integrates built-in skills into SkillsClient initialization with proper priority ordering and adds test coverage

Copilot · 2026-01-21T06:12:13Z

crates/goose/src/agents/builtin_skills/goose_doc_guide.md

+
+## Steps
+
+1. Fetch the doc map from `http://localhost:3000/goose/goose-docs-map.md`


The hardcoded localhost URL http://localhost:3000/goose/ assumes the documentation server is always running locally on port 3000. This may not work in different environments or configurations. Consider making this configurable or using a more robust discovery mechanism.

Copilot · 2026-01-21T06:12:13Z

crates/goose/src/agents/skills_extension.rs

+            if let Ok((metadata, body)) = Self::parse_frontmatter(content) {
+                skills.insert(
+                    metadata.name.clone(),
+                    Skill {
+                        metadata,
+                        body,
+                        directory: PathBuf::new(),
+                        supporting_files: vec![],
+                    },
+                );


Errors during built-in skill parsing are silently ignored. If a built-in skill file has invalid frontmatter, it will fail to load without any logging or error reporting. Consider logging parse failures or returning a Result to surface issues during development.

Suggested change

if let Ok((metadata, body)) = Self::parse_frontmatter(content) {

skills.insert(

metadata.name.clone(),

Skill {

metadata,

body,

directory: PathBuf::new(),

supporting_files: vec![],

},

);

match Self::parse_frontmatter(content) {

Ok((metadata, body)) => {

skills.insert(

metadata.name.clone(),

Skill {

metadata,

body,

directory: PathBuf::new(),

supporting_files: vec![],

},

);

}

Err(e) => {

tracing::warn!(error = ?e, "Failed to parse built-in skill frontmatter; built-in skill will be skipped");

}

Copilot · 2026-01-21T06:12:13Z

crates/goose/src/agents/skills_extension.rs

+        // Load built-in skills first (lowest priority)
+        let mut skills = Self::load_builtin_skills();
+
+        // Discover filesystem skills (can override built-in skills)
        let directories = Self::get_default_skill_directories()
            .into_iter()
            .filter(|d| d.exists())
            .collect::<Vec<_>>();
-        let skills = Self::discover_skills_in_directories(&directories);
+        let fs_skills = Self::discover_skills_in_directories(&directories);
+        skills.extend(fs_skills);

        let mut client = Self { info, skills };
        client.info.instructions = Some(client.generate_instructions());
        Ok(client)
    }


Test coverage is missing for the core override behavior introduced in this PR - verifying that filesystem skills can override built-in skills with the same name. Consider adding a test that loads a built-in skill and then overrides it with a filesystem skill to ensure the priority ordering works correctly.

Copilot · 2026-01-21T06:12:14Z

crates/goose/src/agents/builtin_skills/goose_doc_guide.md

+description: Reference goose documentation to create, configure, or explain goose-specific features like recipes, extensions, sessions, and providers. You MUST fetch relevant Goose docs before answering. You MUST NOT rely on training data or assumptions for any goose-specific fields, values, names, syntax, or commands.
+---
+
+Use this skill when working with **goose-specific features**:
+- Creating or editing recipes
+- Configuring extensions or providers
+- Explaining how goose features work
+- Any goose configuration or setup task
+
+Do NOT use this skill for:
+- General coding tasks unrelated to goose
+- Running existing recipes (just run them directly)
+
+## Steps
+
+1. Fetch the doc map from `http://localhost:3000/goose/goose-docs-map.md`
+2. Search the doc map for pages relevant to the user's topic
+3. Use the EXACT paths from the doc map. For example:
+   - If doc map shows: `docs/guides/sessions/session-management.md`
+   - Fetch: `http://localhost:3000/goose/docs/guides/sessions/session-management.md`
+   Do NOT modify or guess paths. You can make multiple fetch calls in parallel
+4. **When creating or modifying goose configuration files (recipes, extension configs, etc.):**
+   - First, fetch the schema/reference documentation to understand all available fields and requirements
+   - Then, fetch at least one complete working example from the docs to see the correct structure and format in practice
+   - **BEFORE writing the file, explicitly extract and show the relevant code snippet from the example that you will use as a template**
+   - Use BOTH together: the schema for completeness and validation, the example for correct syntax and structure
+   - If there is a conflict between the schema and the example, follow the example for structure and syntax, but do not introduce fields or values that are not documented in the schema
+   - **AFTER creating or editing the file, verify ALL goose-specific sections by comparing them against the fetched examples and explicitly state which documentation example you used for each section**
+5. Use the fetched documentation to help the user with their task
+6. At the end of the response, list the documentation page links that were used to perform the task. 
+   - **Format links by removing the `.md` suffix from the fetched URL**
+   - Example: If you fetched `http://localhost:3000/goose/docs/guides/sessions/session-management.md`, 
+     list it as `http://localhost:3000/goose/docs/guides/sessions/session-management`
+   - Only include links that were actually fetched and referenced
+
+## Strict Requirements
+1. You MUST fetch relevant Goose documentation before providing any goose-specific information.


The text mentions "Goose docs" and "Goose documentation" (capitalized). According to the project naming convention, the project should be referred to as "goose" (lowercase), even at the start of sentences.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Copilot · 2026-01-22T03:32:58Z

crates/goose/src/agents/builtin_skills/goose_doc_guide.md

+   - [ ] For EVERY goose-specific command in your answer: Search feteched files to verify it exists
+   - [ ] For EVERY goose-specific field in your answer: Search feteched files to verify it exists  
+   - [ ] For EVERY usage instruction in your answer: Search feteched files to verify it exists


Typo in "feteched" should be "fetched".

Suggested change

- [ ] For EVERY goose-specific command in your answer: Search feteched files to verify it exists

- [ ] For EVERY goose-specific field in your answer: Search feteched files to verify it exists

- [ ] For EVERY usage instruction in your answer: Search feteched files to verify it exists

- [ ] For EVERY goose-specific command in your answer: Search fetched files to verify it exists

- [ ] For EVERY goose-specific field in your answer: Search fetched files to verify it exists

- [ ] For EVERY usage instruction in your answer: Search fetched files to verify it exists

Copilot · 2026-01-22T03:32:58Z

crates/goose/src/agents/builtin_skills/goose_doc_guide.md

+      - **Search the fetched docs to extract the complete schema for each element you plan to use**
+      - Extract example snippets to understand usage patterns
+      - Create your configuration based on reference specs, following example patterns
+      - **⚠️ STOP: Before showing the user, verify output content MUST match the schema and reference in goose the official documentation:**


Awkward phrasing: "reference in goose the official documentation" should be "reference in the official goose documentation".

Suggested change

- **⚠️ STOP: Before showing the user, verify output content MUST match the schema and reference in goose the official documentation:**

- **⚠️ STOP: Before showing the user, verify output content MUST match the schema and reference in the official goose documentation:**

* main: (41 commits) chore: tweak release docs (#6571) fix(goose): propagate session_id across providers and MCP (#6584) increase worker threads for ci (#6614) docs: todo tutorial update (#6613) Added goose doc map md file for goose agent to find relevant doc easily. (#6598) add back goose branding to home (#6617) fix: actually set the working dir for extensions from session (#6612) Multi chat (#6428) Lifei/fixed accumulated token count (#6587) Dont show MCP UI/Apps until tool is approved (#6492) docs: max tokens config (#6596) User configurable templates (#6420) docs: http proxy environment variables (#6594) feat: exclude subagent tool from code_execution filtering (#6531) Fix path for global agent skills (#6591) recipes: add mcp server (#6552) feat(gcp-vertex): add model list with org policy filtering (#6393) chore: encourage extension searching (#6582) blog: mobile apps consolidation and roadmap (#6580) chore: remove unused dependencies in cargo.toml (#6561) ...

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

michaelneale

I think a great idea.

dianed-square · 2026-01-22T17:56:49Z

crates/goose/src/agents/builtin_skills/skills/goose_doc_guide.md

+   - If doc map shows: `docs/guides/sessions/session-management.md`
+   - Fetch: `https://block.github.io/goose/docs/guides/sessions/session-management.md`
+   - Do NOT modify or guess paths. 
+   - **ONLY fetch paths that are explicitly listed in the doc map - do not guess or infer URLs**


Looks like only a subset of pages are listed in goose-docs-map.md (currently 48 of ~142 pages). Is this too stringent?

Hi @dianed-square!

Thanks for reviewing this PR.

I only included "Get Started" and "Guides" in the map file as they contain the most relevant information for this skill. Too much content makes it harder for goose to find and focus on what's relevant.

FYI: PR to generate the map: #6598.

👍 Thanks for creating this!

* main: docs: ml-based prompt injection detection (#6627) Strip the audience for compacting (#6646) chore(release): release version 1.21.0 (minor) (#6634) add collapsable chat nav (#6649) fix: capitalize Rust in CONTRIBUTING.md (#6640) chore(deps): bump lodash from 4.17.21 to 4.17.23 in /ui/desktop (#6623) Vibe mcp apps (#6569) Add session forking capability (#5882) chore(deps): bump lodash from 4.17.21 to 4.17.23 in /documentation (#6624) fix(docs): use named import for globby v13 (#6639) PR Code Review (#6043) fix(docs): use dynamic import for globby ESM module (#6636) chore: trigger CI Document tab completion (#6635) Install goose-mcp crate dependencies (#6632) feat(goose): standardize agent-session-id for session correlation (#6626)

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Copilot · 2026-01-22T22:58:26Z

crates/goose/src/agents/skills_extension.rs

+        skills.extend(fs_skills);



Filesystem skills will silently override builtin skills with the same name. When skills.extend(fs_skills) is called (line 76), any filesystem skill with a name matching a builtin skill (like "goose-doc-guide") will replace the builtin version. This could confuse users who expect the builtin skill to be available.

Consider either: (1) documenting this behavior so users understand the override mechanism, or (2) inverting the order so filesystem skills are loaded first and builtin skills supplement them, or (3) detecting conflicts and logging a warning when a filesystem skill shadows a builtin skill.

Suggested change

skills.extend(fs_skills);

// Merge filesystem-discovered skills, warning if they shadow builtin skills.

for (name, skill) in fs_skills {

if skills.contains_key(&name) {

eprintln!(

"Warning: filesystem skill \"{}\" overrides builtin skill with the same name",

name

);

}

skills.insert(name, skill);

}

Copilot · 2026-01-22T22:58:27Z

crates/goose/src/agents/builtin_skills/mod.rs

+static BUILTIN_SKILLS_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/src/agents/builtin_skills");
+
+pub fn get_all_builtin_skills() -> Vec<&'static str> {
+    BUILTIN_SKILLS_DIR
+        .files()
+        .filter(|f| f.path().extension().is_some_and(|ext| ext == "md"))


The mod.rs file will be included in the embedded directory by include_dir!. This means the filter on line 8 will see mod.rs (without .md extension) in addition to .md files. While this works because mod.rs is filtered out by the extension check, it's worth noting that the directory being embedded includes the Rust source file itself.

This is not a bug but could be surprising. Consider adding a comment explaining that the macro embeds the entire directory including mod.rs, which is filtered out at runtime.

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated no new comments.

Files not reviewed (1)

ui/desktop/package-lock.json: Language not supported

Signed-off-by: fbalicchia <fbalicchia@cuebiq.com>

* origin/main: Fix GCP Vertex AI global endpoint support for Gemini 3 models (#6187) fix: macOS keychain infinite prompt loop (#6620) chore: reduce duplicate or unused cargo deps (#6630) feat: codex subscription support (#6600) smoke test allow pass for flaky providers (#6638) feat: Add built-in skill for goose documentation reference (#6534) Native images (#6619) docs: ml-based prompt injection detection (#6627) Strip the audience for compacting (#6646) chore(release): release version 1.21.0 (minor) (#6634) add collapsable chat nav (#6649) fix: capitalize Rust in CONTRIBUTING.md (#6640) chore(deps): bump lodash from 4.17.21 to 4.17.23 in /ui/desktop (#6623) Vibe mcp apps (#6569) Add session forking capability (#5882) chore(deps): bump lodash from 4.17.21 to 4.17.23 in /documentation (#6624) fix(docs): use named import for globby v13 (#6639) PR Code Review (#6043) fix(docs): use dynamic import for globby ESM module (#6636) # Conflicts: # Cargo.lock # crates/goose-server/src/routes/session.rs

lifeizhou-ap added 2 commits January 16, 2026 17:48

generated goose doc map md file

d13e888

added built-in skills for goose doc guide

41d980b

lifeizhou-ap changed the title ~~Lifei/goose doc skill~~ feat: Add built-in skill for goose documentation reference Jan 16, 2026

lifeizhou-ap added 2 commits January 20, 2026 21:18

polish skill file

1bc6394

added test for goose doc map

a0d92a2

lifeizhou-ap mentioned this pull request Jan 21, 2026

Added goose doc map md file for goose agent to find relevant doc easily. #6598

Merged

10 tasks

lifeizhou-ap added 3 commits January 21, 2026 15:00

Revert "added test for goose doc map"

edc28dc

This reverts commit a0d92a2.

Revert "generated goose doc map md file"

ca0f4ca

This reverts commit d13e888.

make the skill prompt better

c1b06f8

lifeizhou-ap marked this pull request as ready for review January 21, 2026 06:08

Copilot AI review requested due to automatic review settings January 21, 2026 06:08

Copilot started reviewing on behalf of lifeizhou-ap January 21, 2026 06:09 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

lifeizhou-ap added 2 commits January 21, 2026 23:12

clean up

f294d5b

add more restriction on skill content

3dcb94b

Copilot AI review requested due to automatic review settings January 22, 2026 03:29

Copilot started reviewing on behalf of lifeizhou-ap January 22, 2026 03:30 View session

Copilot AI reviewed Jan 22, 2026

View reviewed changes

lifeizhou-ap added 2 commits January 22, 2026 14:35

more restrictions

05b078c

Copilot AI review requested due to automatic review settings January 22, 2026 04:02

Copilot started reviewing on behalf of lifeizhou-ap January 22, 2026 04:03 View session

Copilot AI reviewed Jan 22, 2026

View reviewed changes

adjust skill to create more accurate result

94bdc32

angiejones requested review from blackgirlbytes and dianed-square January 22, 2026 07:11

michaelneale approved these changes Jan 22, 2026

View reviewed changes

dianed-square reviewed Jan 22, 2026

View reviewed changes

wording

79b23fe

lifeizhou-ap added 2 commits January 23, 2026 09:54

format

d7da411

Copilot AI review requested due to automatic review settings January 22, 2026 22:54

Copilot started reviewing on behalf of lifeizhou-ap January 22, 2026 22:55 View session

Copilot AI reviewed Jan 22, 2026

View reviewed changes

dianed-square approved these changes Jan 22, 2026

View reviewed changes

lifeizhou-ap added 2 commits January 23, 2026 10:34

moved skill file into specific folder

0fd20e4

format again

53e6f1d

Copilot AI review requested due to automatic review settings January 22, 2026 23:41

Copilot started reviewing on behalf of lifeizhou-ap January 22, 2026 23:41 View session

Copilot AI reviewed Jan 22, 2026

View reviewed changes

lifeizhou-ap merged commit 383ae71 into main Jan 23, 2026
25 checks passed

lifeizhou-ap deleted the lifei/goose-doc-skill branch January 23, 2026 00:02

fbalicchia pushed a commit to fbalicchia/goose that referenced this pull request Jan 23, 2026

feat: Add built-in skill for goose documentation reference (block#6534)

9b6e1dc

Signed-off-by: fbalicchia <fbalicchia@cuebiq.com>


		## Steps

		1. Fetch the doc map from `http://localhost:3000/goose/goose-docs-map.md`

	- ⚠️ STOP: Before showing the user, verify output content MUST match the schema and reference in goose the official documentation:
	- ⚠️ STOP: Before showing the user, verify output content MUST match the schema and reference in the official goose documentation:

-        skills.extend(fs_skills);
+        // Merge filesystem-discovered skills, warning if they shadow builtin skills.
+        for (name, skill) in fs_skills {
+            if skills.contains_key(&name) {
+                eprintln!(
+                    "Warning: filesystem skill \"{}\" overrides builtin skill with the same name",
+                    name
+                );
+            }
+            skills.insert(name, skill);
+        }

feat: Add built-in skill for goose documentation reference #6534

feat: Add built-in skill for goose documentation reference #6534

Uh oh!

Conversation

lifeizhou-ap commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of Change

AI Assistance

Testing

Uh oh!

github-actions bot commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-01-21 01:11 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

michaelneale left a comment

Choose a reason for hiding this comment

Uh oh!

dianed-square Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

lifeizhou-ap Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

dianed-square Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

lifeizhou-ap commented Jan 16, 2026 •

edited

Loading

github-actions bot commented Jan 16, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-01-21 01:11 UTC.
Preview will be ready when the GitHub Pages deployment is complete.