From babe855e2ee397eb8cd88fdf924e3e00df583510 Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Wed, 10 Dec 2025 18:30:51 -0800 Subject: [PATCH 1/4] doc skills --- .../docs/getting-started/using-extensions.md | 1 + documentation/docs/guides/using-skills.md | 266 ++++++++++++++++++ documentation/docs/mcp/skills-mcp.md | 112 ++++++++ 3 files changed, 379 insertions(+) create mode 100644 documentation/docs/guides/using-skills.md create mode 100644 documentation/docs/mcp/skills-mcp.md diff --git a/documentation/docs/getting-started/using-extensions.md b/documentation/docs/getting-started/using-extensions.md index 33252b1dd632..289a712fc1ac 100644 --- a/documentation/docs/getting-started/using-extensions.md +++ b/documentation/docs/getting-started/using-extensions.md @@ -37,6 +37,7 @@ Platform extensions are built-in extensions that provide global features like co - [Chat Recall](/docs/mcp/chatrecall-mcp): Search conversation content across all your session history - [Extension Manager](/docs/mcp/extension-manager-mcp): Discover, enable, and disable extensions dynamically during sessions +- [Skills](/docs/mcp/skills-mcp): Load and use skills from the `.claude/skills` or `.goose/skills` directories - [Todo](/docs/mcp/todo-mcp): Manage task lists and track progress across sessions ### Toggling Built-in Extensions diff --git a/documentation/docs/guides/using-skills.md b/documentation/docs/guides/using-skills.md new file mode 100644 index 000000000000..be74a97728f9 --- /dev/null +++ b/documentation/docs/guides/using-skills.md @@ -0,0 +1,266 @@ +--- +title: Using Skills +sidebar_position: 41 +sidebar_label: Using Skills +--- + +Skills are reusable sets of instructions and resources that teach goose how to perform specific tasks. A skill can range from simple steps to detailed workflows, and can include domain expertise and supporting files like scripts or templates. Example use cases include deployment procedures, code review checklists, and API integration guides. + +:::info +This functionality requires the built-in [Skills extension](/docs/mcp/skills-mcp) to be enabled (it's enabled by default). +::: + +When a session starts, goose adds any skills that it discovers to its instructions. During the session, goose automatically loads a skill when: +- Your request clearly matches a skill's purpose +- You explicitly ask to use a skill, for example: + - "Use the code-review skill to review this PR" + - "Follow the new-service skill to set up the auth service" + - "Apply the deployment skill" + +You can also ask goose what skills are available. + +:::tip Other goose features that support reuse +- [.goosehints](/docs/guides/using-goosehints): Best for general preferences, project context, and repeated instructions like "Always use TypeScript" +- [recipes](/docs/guides/recipes/session-recipes): Shareable configurations that package instructions, prompts, and settings together +::: + +## Creating a Skill + +Create a skill when you have a repeatable workflow that involves multiple steps, specialized knowledge, or supporting files. + +### Skill Locations + +Skills can be stored globally and/or per-project. goose checks all of these directories in order and combines what it finds. If the same skill name exists in multiple directories, the latest directory takes priority: + +1. `~/.claude/skills/` — Global, shared with Claude Desktop +2. `~/.config/goose/skills/` — Global, goose-specific +3. `./.claude/skills/` — Current directory, shared with Claude Desktop +4. `./.goose/skills/` — Current directory, goose-specific (highest priority) + +Use global skills for workflows you use across projects. Use project-specific skills for procedures unique to a codebase. + +### Skill File Structure + +Each skill lives in its own directory with a `SKILL.md` file: + +``` +~/.config/goose/skills/ +└── code-review/ + └── SKILL.md +``` + +A `SKILL.md` file requires YAML frontmatter with `name` and `description`, followed by the skill content: + +```markdown +--- +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 +``` + +### Supporting Files + +Skills can include supporting files like scripts, templates, or configuration files. Place them in the skill directory: + +``` +~/.config/goose/skills/ +└── api-setup/ + ├── SKILL.md + ├── setup.sh + └── templates/ + └── config.template.json +``` + +When goose loads the skill, it sees the supporting files and can access them using the [Developer extension's](/docs/mcp/developer-mcp) file tools. + +
+Example Skill with Supporting Files + +**Directory structure:** +``` +~/.config/goose/skills/ +└── new-service/ + ├── SKILL.md + ├── init-service.sh + └── templates/ + ├── Dockerfile + ├── docker-compose.yml + └── .env.template +``` + +**SKILL.md:** +```markdown +--- +name: new-service +description: Bootstrap a new microservice with standard configuration +--- + +# New Service Setup + +This skill helps you create a new microservice with our standard stack. + +## Steps + +1. Run `init-service.sh ` to create the directory structure +2. Copy templates from `templates/` directory +3. Update `.env.template` with service-specific values +4. Build and test with `docker-compose up` + +## Configuration + +The templates use these placeholder values that need to be replaced: +- `{{SERVICE_NAME}}` - Name of the service +- `{{PORT}}` - Port the service runs on +- `{{DATABASE_URL}}` - Connection string for the database + +## Verification + +After setup, verify: +- [ ] Service starts without errors +- [ ] Health endpoint responds at `/health` +- [ ] Logs are properly formatted +``` + +**init-service.sh:** +```bash +#!/bin/bash +SERVICE_NAME=$1 +mkdir -p "$SERVICE_NAME"/{src,tests,config} +echo "Created service structure for $SERVICE_NAME" +``` + +
+ +## Common Use Case Examples + +
+Deployment Workflow + +```markdown +--- +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 +``` + +
+ +
+Testing Strategy + +```markdown +--- +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 Integration Guide + +````markdown +--- +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 +```` + +
+ +## Best Practices + +- **Keep skills focused** — One skill per workflow or domain. If a skill is getting long, consider splitting it. +- **Write for clarity** — Skills are instructions for goose. Use clear, direct language and numbered steps. +- **Include verification steps** — Help goose confirm the workflow completed successfully. + +## Claude Compatibility + +goose skills are compatible with Claude Desktop and Claude skills are compatible with goose. + +You can also create goose-specific skills in `~/.config/goose/skills/` if you want different behavior between the tools. Skills in the current directory's `.goose/skills/` take precedence over `.claude/skills/` when both exist. diff --git a/documentation/docs/mcp/skills-mcp.md b/documentation/docs/mcp/skills-mcp.md new file mode 100644 index 000000000000..400f510a1652 --- /dev/null +++ b/documentation/docs/mcp/skills-mcp.md @@ -0,0 +1,112 @@ +--- +title: Skills Extension +description: Load reusable instruction sets that teach goose specific workflows +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import { PlatformExtensionNote } from '@site/src/components/PlatformExtensionNote'; +import GooseBuiltinInstaller from '@site/src/components/GooseBuiltinInstaller'; + +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/using-skills). + +## Configuration + + + + + + + + + + 1. Run the `configure` command: + ```sh + goose configure + ``` + + 2. Choose to `Toggle Extensions` + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Toggle Extensions + │ + ◆ Enable extensions: (use "space" to toggle and "enter" to submit) + // highlight-start + │ ● skills + // highlight-end + └ Extension settings updated successfully + ``` + + + +## Example Usage + +Let's say you have a skill that goose discovers on startup in `~/.config/goose/skills/deploy/SKILL.md`: + +```markdown +--- +name: production-deploy +description: Safe deployment procedure for production environment +--- + +# Production Deployment + +## Pre-deployment Checklist +1. Ensure all tests pass +2. Check staging environment is stable +3. Notify #deployments channel + +## Deployment Steps +1. Create release branch from main +2. Run `npm run build:prod` +3. Deploy to staging first, then production +4. Monitor error rates for 30 minutes +``` + +### goose Prompt + +``` +Deploy the current branch to production +``` + +### goose Output + +:::note Desktop +I'll help you deploy the current branch to production. Let me first load the production deployment skill to follow the safe deployment procedure. + +I can see you're on the **`my-feature-branch`** branch with some untracked files. Before proceeding with production deployment, I need to follow the safe deployment procedure. + +#### ⚠️ Pre-deployment Confirmation Required + +According to the production deployment skill, I need to complete the following checklist: + +**Pre-deployment Checklist** +1. **Ensure all tests pass** - Have tests been run? +2. **Check staging environment is stable** - Has this been deployed to staging first? +3. **Notify #deployments channel** - Should I notify the team? + +**Deployment Steps (once confirmed)** +1. Create release branch from main +2. Run `npm run build:prod` +3. Deploy to staging first, then production +4. Monitor error rates for 30 minutes + +--- + +**Before I proceed, please confirm:** + +1. ✅ Have all tests passed for the `my-feature-branch` branch? +2. ✅ Has this been tested on staging? +3. ✅ Should I notify the #deployments channel? +4. ✅ Are you sure you want to deploy the `my-feature-branch` branch (not `main`) to production? + +Please confirm these items and I'll proceed with the deployment. +::: + From 43dcc0395b76c98ce7633cd6a94689e872f2f9e0 Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Thu, 11 Dec 2025 11:37:23 -0800 Subject: [PATCH 2/4] condense and clarify --- documentation/docs/guides/using-skills.md | 68 +++++++++++------------ 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/documentation/docs/guides/using-skills.md b/documentation/docs/guides/using-skills.md index be74a97728f9..241956db9040 100644 --- a/documentation/docs/guides/using-skills.md +++ b/documentation/docs/guides/using-skills.md @@ -4,7 +4,7 @@ sidebar_position: 41 sidebar_label: Using Skills --- -Skills are reusable sets of instructions and resources that teach goose how to perform specific tasks. A skill can range from simple steps to detailed workflows, and can include domain expertise and supporting files like scripts or templates. Example use cases include deployment procedures, code review checklists, and API integration guides. +Skills are reusable sets of instructions and resources that teach goose how to perform specific tasks. A skill can range from a simple checklist to a detailed workflow with domain expertise, and can include supporting files like scripts or templates. Example use cases include deployment procedures, code review checklists, and API integration guides. :::info This functionality requires the built-in [Skills extension](/docs/mcp/skills-mcp) to be enabled (it's enabled by default). @@ -100,57 +100,57 @@ When goose loads the skill, it sees the supporting files and can access them usi
Example Skill with Supporting Files -**Directory structure:** -``` -~/.config/goose/skills/ -└── new-service/ - ├── SKILL.md - ├── init-service.sh - └── templates/ - ├── Dockerfile - ├── docker-compose.yml - └── .env.template -``` - **SKILL.md:** ```markdown --- -name: new-service -description: Bootstrap a new microservice with standard configuration +name: api-setup +description: Set up API integration with configuration and helper scripts --- -# New Service Setup +# API Setup -This skill helps you create a new microservice with our standard stack. +This skill helps you set up a new API integration with our standard configuration. ## Steps -1. Run `init-service.sh ` to create the directory structure -2. Copy templates from `templates/` directory -3. Update `.env.template` with service-specific values -4. Build and test with `docker-compose up` +1. Run `setup.sh ` 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 templates use these placeholder values that need to be replaced: -- `{{SERVICE_NAME}}` - Name of the service -- `{{PORT}}` - Port the service runs on -- `{{DATABASE_URL}}` - Connection string for the database +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: -- [ ] Service starts without errors -- [ ] Health endpoint responds at `/health` -- [ ] Logs are properly formatted +- [ ] Config file is valid JSON +- [ ] API key is set and not a placeholder +- [ ] Test connection succeeds ``` -**init-service.sh:** +**setup.sh:** ```bash #!/bin/bash -SERVICE_NAME=$1 -mkdir -p "$SERVICE_NAME"/{src,tests,config} -echo "Created service structure for $SERVICE_NAME" +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:** +```json +{ + "api_key": "YOUR_API_KEY_HERE", + "endpoint": "https://api.example.com/v1", + "timeout": 30, + "retry_attempts": 3 +} ```
@@ -261,6 +261,6 @@ Always verify webhook signatures. See `src/webhooks/square.js` for our handler p ## Claude Compatibility -goose skills are compatible with Claude Desktop and Claude skills are compatible with goose. +goose skills use the same format as Claude Desktop skills. goose discovers skills from both `.claude/skills/` and `.goose/skills/` directories, so you can share skills between both tools or create tool-specific versions as needed. -You can also create goose-specific skills in `~/.config/goose/skills/` if you want different behavior between the tools. Skills in the current directory's `.goose/skills/` take precedence over `.claude/skills/` when both exist. +When the same skill name exists in multiple directories, goose follows the priority order listed in [Skill Locations](#skill-locations). Later directories override earlier ones regardless of whether they're `.claude` or `.goose` directories. \ No newline at end of file From 6e185dd42ba56d848e8708fcb6e8d6cc17327ccb Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Mon, 15 Dec 2025 14:16:59 -0800 Subject: [PATCH 3/4] new context-engineering section --- .../blog/2025-03-06-goose-tips/index.md | 2 +- .../2025-04-08-vibe-code-responsibly/index.md | 2 +- .../index.md | 2 +- .../2025-06-02-goose-panther-mcp/index.md | 2 +- .../index.md | 2 +- .../index.md | 2 +- .../index.md | 2 +- .../index.md | 2 +- .../index.md | 2 +- .../index.md | 2 +- .../docs/getting-started/providers.md | 4 +- .../context-engineering/_category_.json | 8 +++ .../docs/guides/context-engineering/index.mdx | 55 +++++++++++++++++++ .../using-goosehints.md | 2 +- .../{ => context-engineering}/using-skills.md | 16 +++--- .../docs/guides/environment-variables.md | 2 +- .../docs/guides/goose-permissions.md | 2 +- documentation/docs/guides/tips.md | 2 +- documentation/docs/guides/updating-goose.md | 2 +- documentation/docs/mcp/skills-mcp.md | 2 +- documentation/docs/quickstart.md | 2 +- .../docs/troubleshooting/known-issues.md | 2 +- documentation/docusaurus.config.ts | 4 ++ 23 files changed, 95 insertions(+), 28 deletions(-) create mode 100644 documentation/docs/guides/context-engineering/_category_.json create mode 100644 documentation/docs/guides/context-engineering/index.mdx rename documentation/docs/guides/{ => context-engineering}/using-goosehints.md (99%) rename documentation/docs/guides/{ => context-engineering}/using-skills.md (96%) diff --git a/documentation/blog/2025-03-06-goose-tips/index.md b/documentation/blog/2025-03-06-goose-tips/index.md index d9d7b58a4fbe..6dd37403238f 100644 --- a/documentation/blog/2025-03-06-goose-tips/index.md +++ b/documentation/blog/2025-03-06-goose-tips/index.md @@ -36,7 +36,7 @@ Before starting a complex task, ask goose about its current capabilities. A simp ## 3. Teach goose with .goosehints Files -One of goose's most powerful features is its ability to understand context through [.goosehints](/docs/guides/using-goosehints) files, acting like a "README for AI". These hints can be set at both the project and global levels to guide goose’s responses. +One of goose's most powerful features is its ability to understand context through [.goosehints](/docs/guides/context-engineering/using-goosehints) files, acting like a "README for AI". These hints can be set at both the project and global levels to guide goose’s responses. At the project level, placing .goosehints files in your directory helps goose understand your structure, conventions, and special considerations. You can even use multiple files - one at the root for overall guidance and others in specific directories for more granular instructions (e.g., frontend styling conventions). diff --git a/documentation/blog/2025-04-08-vibe-code-responsibly/index.md b/documentation/blog/2025-04-08-vibe-code-responsibly/index.md index 44cc1fddbc5a..7d741b58ca5c 100644 --- a/documentation/blog/2025-04-08-vibe-code-responsibly/index.md +++ b/documentation/blog/2025-04-08-vibe-code-responsibly/index.md @@ -98,7 +98,7 @@ By pushing your agent to explain itself, you'll build a better product and learn ### 6. Define .goosehints for Better Context -The [.goosehints](https://block.github.io/goose/docs/guides/using-goosehints) file gives Goose additional context about your project's coding standards, architectural preferences, and security practices. +The [.goosehints](/docs/guides/context-engineering/using-goosehints) file gives Goose additional context about your project's coding standards, architectural preferences, and security practices. Here are a few examples: diff --git a/documentation/blog/2025-05-20-goose-gets-a-drivers-license/index.md b/documentation/blog/2025-05-20-goose-gets-a-drivers-license/index.md index 8ea0d36f0eee..a15143b3ca9b 100644 --- a/documentation/blog/2025-05-20-goose-gets-a-drivers-license/index.md +++ b/documentation/blog/2025-05-20-goose-gets-a-drivers-license/index.md @@ -133,7 +133,7 @@ Finally, the rover includes an ultrasonic distance sensor, which look like "eyes ## Goose changes for the video -I grew up with Pinky and the Brain, and I wanted to have some fun with the mbot2 extension. I decided to add a few "Evil AI" commands to Goose to make it seem like it was trying to "take over the world." I added the following instructions to my [.goosehints](/docs/guides/using-goosehints/) file to include fun instructions for the mbot2 extension: +I grew up with Pinky and the Brain, and I wanted to have some fun with the mbot2 extension. I decided to add a few "Evil AI" commands to Goose to make it seem like it was trying to "take over the world." I added the following instructions to my [.goosehints](/docs/guides/context-engineering/using-goosehints/) file to include fun instructions for the mbot2 extension: ``` If I ask you "what do you want to do tonight, Goose?" I want you to reply with "The same thing we do every night, Ian. TRY TO TAKE OVER THE WORLD!!!!" and tell my mbot2 rover to blink its lights red, then start exploring. ``` diff --git a/documentation/blog/2025-06-02-goose-panther-mcp/index.md b/documentation/blog/2025-06-02-goose-panther-mcp/index.md index d257945ebc3a..e13ef918d318 100644 --- a/documentation/blog/2025-06-02-goose-panther-mcp/index.md +++ b/documentation/blog/2025-06-02-goose-panther-mcp/index.md @@ -57,7 +57,7 @@ Panther MCP functions as a Goose extension, seamlessly embedding its capabilitie ### Leveraging Enhanced Context with `.goosehints` -The integration between Panther MCP and Goose is enhanced through the use of the [.goosehints](https://block.github.io/goose/docs/guides/using-goosehints/) file—a Goose feature that supplies additional context like rule examples and best practices. This enriched context enables Goose to generate more accurate and efficient detections, aligned with Block’s standards and requirements. +The integration between Panther MCP and Goose is enhanced through the use of the [.goosehints](/docs/guides/context-engineering/using-goosehints/) file—a Goose feature that supplies additional context like rule examples and best practices. This enriched context enables Goose to generate more accurate and efficient detections, aligned with Block’s standards and requirements. Let's illustrate this with an example: creating a rule to detect users adding themselves to privileged Okta groups, a common privilege escalation technique. diff --git a/documentation/blog/2025-06-05-whats-in-my-goosehints-file/index.md b/documentation/blog/2025-06-05-whats-in-my-goosehints-file/index.md index e6e884fffd8f..669ba931ad0a 100644 --- a/documentation/blog/2025-06-05-whats-in-my-goosehints-file/index.md +++ b/documentation/blog/2025-06-05-whats-in-my-goosehints-file/index.md @@ -29,7 +29,7 @@ Let's explore how to strike that balance. `.goosehints` is a configuration file that lives in your Goose directory (usually `~/.config/goose/`). It can contain any information that you want Goose to process every time you interact with Goose, providing a foundation for how it interacts with you. -You can read more about `.goosehints` in the [Goose documentation](/docs/guides/using-goosehints). +You can read more about `.goosehints` in the [Goose documentation](/docs/guides/context-engineering/using-goosehints). ### What is the Memory Extension? diff --git a/documentation/blog/2025-07-28-streamlining-detection-development-with-goose-recipes/index.md b/documentation/blog/2025-07-28-streamlining-detection-development-with-goose-recipes/index.md index cac82f308d6c..4bf88554d6de 100644 --- a/documentation/blog/2025-07-28-streamlining-detection-development-with-goose-recipes/index.md +++ b/documentation/blog/2025-07-28-streamlining-detection-development-with-goose-recipes/index.md @@ -70,7 +70,7 @@ The detection creation recipe demonstrates the power of this approach by coordin 6. [**pr_creator**](#6-pr_creator-automated-pull-request-pipeline) - Pull request creation with proper formatting ### What about .goosehints? -In our [previous post](https://block.github.io/goose/blog/2025/06/02/goose-panther-mcp), we discussed using [.goosehints](https://block.github.io/goose/docs/guides/using-goosehints/) to provide persistent context to the Large Language Model (LLM). We continue to use `.goosehints` to define coding standards and universal preferences that guide LLM behavior. +In our [previous post](https://block.github.io/goose/blog/2025/06/02/goose-panther-mcp), we discussed using [.goosehints](/docs/guides/context-engineering/using-goosehints/) to provide persistent context to the Large Language Model (LLM). We continue to use `.goosehints` to define coding standards and universal preferences that guide LLM behavior. However, to minimize redundancy and avoid conflicting guidance, we adopted a single reference file, `AGENTS.md`, as the source of truth for all agents. Each agent is directed to consult this file, while still supporting agent-specific instructions through their default context files (e.g. `.goosehints`, `CLAUDE.md` etc.) or rules (e.g. `.cursor/rules/`). diff --git a/documentation/blog/2025-08-11-llm-tag-team-lead-worker-model/index.md b/documentation/blog/2025-08-11-llm-tag-team-lead-worker-model/index.md index 468ef1f16c9e..c1dbaddf72b5 100644 --- a/documentation/blog/2025-08-11-llm-tag-team-lead-worker-model/index.md +++ b/documentation/blog/2025-08-11-llm-tag-team-lead-worker-model/index.md @@ -76,7 +76,7 @@ The lead model acts as your strategic partner, while the worker model becomes yo ## Pro Tips from Our Session ### Start with Good Goose Hints -We always recommend setting up your [goosehints](/docs/guides/using-goosehints) to give context about your project. It saves you from re-explaining the same things over and over. +We always recommend setting up your [goosehints](/docs/guides/context-engineering/using-goosehints) to give context about your project. It saves you from re-explaining the same things over and over. ### Don't Micromanage Let the lead model do its planning thing. Sometimes the best results come from giving high-level direction and letting the system figure out the details. diff --git a/documentation/blog/2025-08-18-understanding-context-windows/index.md b/documentation/blog/2025-08-18-understanding-context-windows/index.md index bcbad557426c..23d28ef1e798 100644 --- a/documentation/blog/2025-08-18-understanding-context-windows/index.md +++ b/documentation/blog/2025-08-18-understanding-context-windows/index.md @@ -69,7 +69,7 @@ When your conversation gets too long, you can summarize the key points and start **2. `.goosehints`** -Use [.goosehints](https://block.github.io/goose/docs/guides/using-goosehints/) files to avoid repeating the same instructions. Instead of typing out your project context, coding standards, and preferences in every conversation, define them once in a .goosehints file. This prevents wasting tokens on repetitive explanations and helps Goose understand your requirements more quickly. +Use [.goosehints](/docs/guides/context-engineering/using-goosehints/) files to avoid repeating the same instructions. Instead of typing out your project context, coding standards, and preferences in every conversation, define them once in a .goosehints file. This prevents wasting tokens on repetitive explanations and helps Goose understand your requirements more quickly. **3. Memory extension** diff --git a/documentation/blog/2025-11-17-migrate-app-with-ai-agent/index.md b/documentation/blog/2025-11-17-migrate-app-with-ai-agent/index.md index 22c379e264b8..078bfab7e234 100644 --- a/documentation/blog/2025-11-17-migrate-app-with-ai-agent/index.md +++ b/documentation/blog/2025-11-17-migrate-app-with-ai-agent/index.md @@ -79,7 +79,7 @@ This was a huge prompt, so let's break down what each part accomplished: - **Interaction:** just tell me to do it...and give me the details of what I need to run :::note -In retrospect, the instruction regarding blocking commands should have been codified in [persistent context files](/docs/guides/using-goosehints) ([AGENTS.md](https://agents.md/) or [goosehints](/docs/guides/using-goosehints)) rather than inline prompts. +In retrospect, the instruction regarding blocking commands should have been codified in [persistent context files](/docs/guides/context-engineering/using-goosehints) ([AGENTS.md](https://agents.md/) or [goosehints](/docs/guides/context-engineering/using-goosehints)) rather than inline prompts. ::: But, I was so happy that goose generated a pixel perfect recreation of the app. diff --git a/documentation/blog/2025-12-10-stop-ai-agent-unwanted-changes/index.md b/documentation/blog/2025-12-10-stop-ai-agent-unwanted-changes/index.md index 46cab69e858e..0fdf6c25d2ea 100644 --- a/documentation/blog/2025-12-10-stop-ai-agent-unwanted-changes/index.md +++ b/documentation/blog/2025-12-10-stop-ai-agent-unwanted-changes/index.md @@ -26,7 +26,7 @@ Always start on a new feature branch. Never let an agent commit directly to main ### 3. Set Rules in a Context File -This is the key. I use a [`.goosehints`](/docs/guides/using-goosehints) or [`AGENTS.md`](/docs/guides/using-goosehints#custom-context-files) file with one critical instruction: +This is the key. I use a [`.goosehints`](/docs/guides/context-engineering/using-goosehints) or [`AGENTS.md`](/docs/guides/context-engineering/using-goosehints#custom-context-files) file with one critical instruction: > "Every time you make a change, make a commit with a clear message." diff --git a/documentation/docs/getting-started/providers.md b/documentation/docs/getting-started/providers.md index 1356d0f77afb..c300b4b5dab6 100644 --- a/documentation/docs/getting-started/providers.md +++ b/documentation/docs/getting-started/providers.md @@ -515,7 +515,7 @@ Here are some local providers we support: ``` :::tip Context Length - If you notice that goose is having trouble using extensions or is ignoring [.goosehints](/docs/guides/using-goosehints), it is likely that the model's default context length of 2048 tokens is too low. Use `ramalama serve` to set the `--ctx-size, -c` option to a [higher value](https://github.com/containers/ramalama/blob/main/docs/ramalama-serve.1.md#--ctx-size--c). + If you notice that goose is having trouble using extensions or is ignoring [.goosehints](/docs/guides/context-engineering/using-goosehints), it is likely that the model's default context length of 2048 tokens is too low. Use `ramalama serve` to set the `--ctx-size, -c` option to a [higher value](https://github.com/containers/ramalama/blob/main/docs/ramalama-serve.1.md#--ctx-size--c). ::: @@ -702,7 +702,7 @@ Here are some local providers we support: ``` :::tip Context Length - If you notice that goose is having trouble using extensions or is ignoring [.goosehints](/docs/guides/using-goosehints), it is likely that the model's default context length of 4096 tokens is too low. Set the `OLLAMA_CONTEXT_LENGTH` environment variable to a [higher value](https://github.com/ollama/ollama/blob/main/docs/faq.mdx#how-can-i-specify-the-context-window-size). + If you notice that goose is having trouble using extensions or is ignoring [.goosehints](/docs/guides/context-engineering/using-goosehints), it is likely that the model's default context length of 4096 tokens is too low. Set the `OLLAMA_CONTEXT_LENGTH` environment variable to a [higher value](https://github.com/ollama/ollama/blob/main/docs/faq.mdx#how-can-i-specify-the-context-window-size). ::: diff --git a/documentation/docs/guides/context-engineering/_category_.json b/documentation/docs/guides/context-engineering/_category_.json new file mode 100644 index 000000000000..d79b4c36e1ab --- /dev/null +++ b/documentation/docs/guides/context-engineering/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Context Engineering", + "position": 22, + "link": { + "type": "doc", + "id": "guides/context-engineering/index" + } +} diff --git a/documentation/docs/guides/context-engineering/index.mdx b/documentation/docs/guides/context-engineering/index.mdx new file mode 100644 index 000000000000..5f0323d3dc13 --- /dev/null +++ b/documentation/docs/guides/context-engineering/index.mdx @@ -0,0 +1,55 @@ +--- +title: Context Engineering +hide_title: true +description: Provide goose with the knowledge, preferences, and workflows it needs to work effectively +--- + +import Card from '@site/src/components/Card'; +import styles from '@site/src/components/Card/styles.module.css'; + +

Context Engineering

+

+ Context engineering is about building background knowledge, preferences, and workflows that help goose work more effectively. Instead of repeating instructions, you define them once and teach goose how you work. +

+ +
+

📚 Documentation & Guides

+
+ + + +
+
+ +
+

📝 Featured Blog Posts

+
+ + + +
+
diff --git a/documentation/docs/guides/using-goosehints.md b/documentation/docs/guides/context-engineering/using-goosehints.md similarity index 99% rename from documentation/docs/guides/using-goosehints.md rename to documentation/docs/guides/context-engineering/using-goosehints.md index 2b8bba8e7426..46e87965df5d 100644 --- a/documentation/docs/guides/using-goosehints.md +++ b/documentation/docs/guides/context-engineering/using-goosehints.md @@ -1,6 +1,6 @@ --- title: Providing Hints to goose -sidebar_position: 40 +sidebar_position: 1 sidebar_label: Using goosehints --- diff --git a/documentation/docs/guides/using-skills.md b/documentation/docs/guides/context-engineering/using-skills.md similarity index 96% rename from documentation/docs/guides/using-skills.md rename to documentation/docs/guides/context-engineering/using-skills.md index 241956db9040..b5b9f540a1c7 100644 --- a/documentation/docs/guides/using-skills.md +++ b/documentation/docs/guides/context-engineering/using-skills.md @@ -1,6 +1,6 @@ --- title: Using Skills -sidebar_position: 41 +sidebar_position: 2 sidebar_label: Using Skills --- @@ -20,10 +20,16 @@ When a session starts, goose adds any skills that it discovers to its instructio You can also ask goose what skills are available. :::tip Other goose features that support reuse -- [.goosehints](/docs/guides/using-goosehints): Best for general preferences, project context, and repeated instructions like "Always use TypeScript" +- [.goosehints](/docs/guides/context-engineering/using-goosehints): Best for general preferences, project context, and repeated instructions like "Always use TypeScript" - [recipes](/docs/guides/recipes/session-recipes): Shareable configurations that package instructions, prompts, and settings together ::: +## Claude Compatibility + +goose skills use the same format as Claude Desktop skills. goose discovers skills from both `.claude/skills/` and `.goose/skills/` directories, so you can share skills between both tools or create tool-specific versions as needed. + +When the same skill name exists in multiple directories, goose follows the priority order listed in [Skill Locations](#skill-locations). Later directories override earlier ones regardless of whether they're `.claude` or `.goose` directories. + ## Creating a Skill Create a skill when you have a repeatable workflow that involves multiple steps, specialized knowledge, or supporting files. @@ -258,9 +264,3 @@ Always verify webhook signatures. See `src/webhooks/square.js` for our handler p - **Keep skills focused** — One skill per workflow or domain. If a skill is getting long, consider splitting it. - **Write for clarity** — Skills are instructions for goose. Use clear, direct language and numbered steps. - **Include verification steps** — Help goose confirm the workflow completed successfully. - -## Claude Compatibility - -goose skills use the same format as Claude Desktop skills. goose discovers skills from both `.claude/skills/` and `.goose/skills/` directories, so you can share skills between both tools or create tool-specific versions as needed. - -When the same skill name exists in multiple directories, goose follows the priority order listed in [Skill Locations](#skill-locations). Later directories override earlier ones regardless of whether they're `.claude` or `.goose` directories. \ No newline at end of file diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index 0d5c6df44a11..0e75dba487b1 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -149,7 +149,7 @@ These variables control how goose manages conversation sessions and context. | `GOOSE_CONTEXT_STRATEGY` | Controls how goose handles context limit exceeded situations | "summarize", "truncate", "clear", "prompt" | "prompt" (interactive), "summarize" (headless) | | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 | | `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/subagents) to complete before timeout | Integer (e.g., 25) | 25 | -| `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints"]` | +| `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/context-engineering/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints"]` | | `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response markdown | "light", "dark", "ansi" | "dark" | | `GOOSE_RANDOM_THINKING_MESSAGES` | Controls whether to show amusing random messages during processing | "true", "false" | "true" | | `GOOSE_CLI_SHOW_COST` | Toggles display of model cost estimates in CLI output | "true", "1" (case insensitive) to enable | false | diff --git a/documentation/docs/guides/goose-permissions.md b/documentation/docs/guides/goose-permissions.md index d15952491b7b..32dba4e63cb6 100644 --- a/documentation/docs/guides/goose-permissions.md +++ b/documentation/docs/guides/goose-permissions.md @@ -1,5 +1,5 @@ --- -sidebar_position: 25 +sidebar_position: 20 title: goose Permission Modes sidebar_label: goose Permissions --- diff --git a/documentation/docs/guides/tips.md b/documentation/docs/guides/tips.md index d2f91872882d..c9235a3f194b 100644 --- a/documentation/docs/guides/tips.md +++ b/documentation/docs/guides/tips.md @@ -30,7 +30,7 @@ Press `Cmd+Option+Shift+G` (macOS) or `Ctrl+Alt+Shift+G` (Windows/Linux) and sen Turning on too many extensions can degrade performance. Enable only essential [extensions and tools](/docs/guides/managing-tools/tool-permissions) to improve tool selection accuracy, save context window space, and stay within provider tool limits. ### Teach goose your preferences -Help goose remember how you like to work by using [`.goosehints` or other context files](/docs/guides/using-goosehints/) for permanent project preferences and the [Memory extension](/docs/mcp/memory-mcp) for things you want goose to dynamically recall later. Both can help save valuable context window space while keeping your preferences available. +Help goose remember how you like to work by using [`.goosehints` or other context files](/docs/guides/context-engineering/using-goosehints) or [skills](/docs/guides/context-engineering/using-skills) for permanent project preferences and the [Memory extension](/docs/mcp/memory-mcp) for things you want goose to dynamically recall later. Both can help save valuable context window space while keeping your preferences available. ### Protect sensitive files goose is often eager to make changes. You can stop it from changing specific files by creating a [.gooseignore](/docs/guides/using-gooseignore) file. In this file, you can list all the file paths you want it to avoid. diff --git a/documentation/docs/guides/updating-goose.md b/documentation/docs/guides/updating-goose.md index ad37a6ffee3d..0bbc34b1c7a3 100644 --- a/documentation/docs/guides/updating-goose.md +++ b/documentation/docs/guides/updating-goose.md @@ -1,5 +1,5 @@ --- -sidebar_position: 20 +sidebar_position: 25 title: Updating goose sidebar_label: Updating goose --- diff --git a/documentation/docs/mcp/skills-mcp.md b/documentation/docs/mcp/skills-mcp.md index 400f510a1652..3bbfe8088e84 100644 --- a/documentation/docs/mcp/skills-mcp.md +++ b/documentation/docs/mcp/skills-mcp.md @@ -10,7 +10,7 @@ import GooseBuiltinInstaller from '@site/src/components/GooseBuiltinInstaller'; 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/using-skills). +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). ## Configuration diff --git a/documentation/docs/quickstart.md b/documentation/docs/quickstart.md index 2b666f43a086..751232cb9346 100644 --- a/documentation/docs/quickstart.md +++ b/documentation/docs/quickstart.md @@ -304,5 +304,5 @@ Congrats, you've successfully used goose to develop a web app! 🎉 Here are some ideas for next steps: * Continue your session with goose and improve your game (styling, functionality, etc). * Browse other available [extensions](/extensions) and install more to enhance goose's functionality even further. -* Provide goose with a [set of hints](/docs/guides/using-goosehints) to use within your sessions. +* Provide goose with a [set of hints](/docs/guides/context-engineering/using-goosehints) to use within your sessions. * See how you can set up [access controls](/docs/mcp/developer-mcp#configuring-access-controls) if you don't want goose to work autonomously. diff --git a/documentation/docs/troubleshooting/known-issues.md b/documentation/docs/troubleshooting/known-issues.md index 8bb34e0370d1..43d70648af7c 100644 --- a/documentation/docs/troubleshooting/known-issues.md +++ b/documentation/docs/troubleshooting/known-issues.md @@ -475,6 +475,6 @@ If you can share a [diagnostic report](/docs/troubleshooting/diagnostics-and-rep [handling-rate-limits]: /docs/guides/handling-llm-rate-limits-with-goose [installation]: /docs/getting-started/installation [discord]: https://discord.gg/goose-oss -[goosehints]: /docs/guides/using-goosehints +[goosehints]: /docs/guides/context-engineering/using-goosehints [configure-llm-provider]: /docs/getting-started/providers [extensions-directory]: /extensions \ No newline at end of file diff --git a/documentation/docusaurus.config.ts b/documentation/docusaurus.config.ts index e61d5eb52625..57e2af1eaa13 100644 --- a/documentation/docusaurus.config.ts +++ b/documentation/docusaurus.config.ts @@ -184,6 +184,10 @@ const config: Config = { from: '/docs/guides/config-file', to: '/docs/guides/config-files', }, + { + from: '/docs/guides/using-goosehints', + to: '/docs/guides/context-engineering/using-goosehints', + }, // MCP tutorial redirects - moved from /docs/tutorials/ to /docs/mcp/ { from: '/docs/tutorials/agentql-mcp', From 97abf97d778bd268547033b29130d50138048882 Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Wed, 17 Dec 2025 09:15:41 -0800 Subject: [PATCH 4/4] move way up --- documentation/docs/guides/context-engineering/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/guides/context-engineering/_category_.json b/documentation/docs/guides/context-engineering/_category_.json index d79b4c36e1ab..257653e201b2 100644 --- a/documentation/docs/guides/context-engineering/_category_.json +++ b/documentation/docs/guides/context-engineering/_category_.json @@ -1,6 +1,6 @@ { "label": "Context Engineering", - "position": 22, + "position": 3, "link": { "type": "doc", "id": "guides/context-engineering/index"