From 493654829fe76942f15681d5a9c17b4b2404ce9f Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Mon, 13 Jul 2026 17:17:07 -0600
Subject: [PATCH] docs: Added workspace-local skills and MCP server
 configuration documentation

---
 MCP-Servers.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++
 Skills.md      | 27 ++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)

diff --git a/MCP-Servers.md b/MCP-Servers.md
index fde3420..d160d51 100644
--- a/MCP-Servers.md
+++ b/MCP-Servers.md
@@ -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:
diff --git a/Skills.md b/Skills.md
index bcb90e2..9ca8461 100644
--- a/Skills.md
+++ b/Skills.md
@@ -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