docs: Added workspace-local skills and MCP server configuration documentation

2026-07-13 17:17:07 -06:00
parent 669187d148
commit 493654829f
2 changed files with 79 additions and 0 deletions
@@ -40,6 +40,58 @@ Every server entry **must** include a `"type"` field set to one of: `"stdio"`, `
 > kit provides. See [Sandbox Compatibility](#sandbox-compatibility) at the bottom of this page for details and
 > common gotchas.

+## Workspace-Local MCP Servers
+
+In addition to the global `functions/mcp.json`, Coyote automatically loads a workspace-local MCP config from `.coyote/mcp.json`
+in the current directory at startup. This lets you ship project-specific MCP servers alongside your code without
+touching your global configuration.
+
+```
+<project-root>/
+└── .coyote/
+    └── mcp.json       # same format as functions/mcp.json
+```
+
+The workspace file uses the exact same format as the global `functions/mcp.json`, including [Vault](Vault) secret
+interpolation via `{{SECRET_NAME}}` syntax. Workspace server names shadow global ones on collision. This means that
+if both files define a server named `my-db`, the workspace version takes precedence.
+
+When workspace MCP servers are loaded, Coyote prints a startup notice listing them:
+
+```
+Loading workspace MCP servers: my-db, project-search
+```
+
+**Error handling:** missing vault secrets and invalid server specs in the workspace file produce a warning and are
+skipped. They do not prevent Coyote from starting (unlike the global file, where missing secrets are a hard error).
+
+### Opting out
+
+To disable workspace MCP loading for a session, pass `--no-workspace-mcp`:
+
+```shell
+coyote --no-workspace-mcp
+```
+
+To disable it permanently in your config:
+
+```yaml
+no_workspace_mcp: true
+```
+
+### Pairing workspace MCPs with workspace skills
+
+Workspace MCP servers can be referenced in `.coyote/skills/` skill frontmatter just like global servers:
+
+```markdown
+---
+description: Run project-specific database queries.
+enabled_mcp_servers: my-db
+---
+```
+
+See [Workspace-Local Skills](Skills#workspace-local-skills) for details.
+
 ## Transport Types

 Coyote supports three MCP transport types:
@@ -66,6 +66,33 @@ it.

 To see complete examples, look at the [bundled built-in skills](https://github.com/Dark-Alex-17/coyote/tree/main/assets/skills).

+## Workspace-Local Skills
+
+In addition to global skills, Coyote discovers skills local to the current working directory. Place a skill under `.coyote/skills/`
+in your project root and it becomes available whenever you run Coyote from that directory (or any subdirectory):
+
+```
+<project-root>/
+└── .coyote/
+    └── skills/
+        └── <skill-name>/
+            └── SKILL.md
+```
+
+Workspace skills work identically to global skills; same `SKILL.md` format, same frontmatter fields, same composition rules.
+The only differences are:
+
+- **Discovery:** Coyote scans `.coyote/skills/` in addition to the global skills directory.
+- **Precedence:** If a workspace skill and a global skill share the same name, the workspace version wins.
+- **Scope:** Workspace skills are only visible when running from that directory tree; they do not appear in other projects.
+
+This is useful for project-specific workflows: a `db-migration` skill with your team's migration conventions, a `deploy`
+skill that loads the project's deployment MCP server, or any other task-specific overlay that doesn't belong in your
+global configuration.
+
+Workspace skills can reference MCP servers from both the global `functions/mcp.json` and the workspace `.coyote/mcp.json`
+(see [Workspace-Local MCP Servers](MCP-Servers#workspace-local-mcp-servers)).
+
 ## Frontmatter

 The YAML frontmatter at the top of `SKILL.md` is where you declare the skill's metadata and what extra capabilities it