diff --git a/docs/chatgpt-coding-workflow.md b/docs/chatgpt-coding-workflow.md index 66062621..1b6b49a6 100644 --- a/docs/chatgpt-coding-workflow.md +++ b/docs/chatgpt-coding-workflow.md @@ -103,6 +103,12 @@ before use. Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed. +Example skills are packaged under `examples/skills/`. The +`examples/skills/executor-local-mcp` skill is a template for using a user's +existing Executor setup from DevSpace shell tools. Copy it into +`~/.devspace/skills` or another active skill directory when ChatGPT should +discover and call local Executor MCP/API integrations. + When `open_workspace` returns matching skills, the model should read the advertised `SKILL.md` before following that skill. diff --git a/docs/configuration.md b/docs/configuration.md index 4c02eb1a..6e539e27 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -134,6 +134,18 @@ DEVSPACE_SKILL_PATHS="$HOME/.claude/skills,$HOME/company/skills" \ npx @waishnav/devspace serve ``` +Example skills are packaged under `examples/skills/`. To teach ChatGPT to use a +local Executor setup for existing MCP/API integrations, copy the packaged skill +into an active skill directory: + +```bash +mkdir -p ~/.devspace/skills/executor-local-mcp +cp examples/skills/executor-local-mcp/SKILL.md ~/.devspace/skills/executor-local-mcp/SKILL.md +``` + +That workflow uses the existing `bash` or `exec_command` tool to run the local +`executor` CLI. It does not add DevSpace bridge tools for every Executor tool. + ## Logging | Variable | Default | diff --git a/examples/skills/executor-local-mcp/SKILL.md b/examples/skills/executor-local-mcp/SKILL.md new file mode 100644 index 00000000..3cf3089c --- /dev/null +++ b/examples/skills/executor-local-mcp/SKILL.md @@ -0,0 +1,68 @@ +--- +name: executor-local-mcp +description: Use the user's local Executor CLI to discover and call existing local MCP/API integrations from DevSpace shell tools. +--- + +# Executor Local MCP + +Use this skill when the user asks to use Executor, local MCP tools, or local +integrations such as Obsidian, Zotero, Thunderbird, browser automation, or other +tools configured in Executor. + +Executor is already available through the user's terminal. Do not ask DevSpace +for additional bridge tools. Use the existing DevSpace shell tool: + +- In minimal or full tool mode, use `bash`. +- In codex tool mode, use `exec_command`. + +## Discovery + +First confirm Executor is installed and reachable when needed: + +```bash +command -v executor +executor service status +``` + +List configured tool sources: + +```bash +executor tools sources +``` + +Search for candidate tools before calling one: + +```bash +executor tools search "zotero collections" --limit 20 +``` + +Describe unfamiliar tools before invoking them: + +```bash +executor tools describe zotero.user.default.zotero_list_collections +``` + +## Calling Tools + +Call tools with `executor call`, splitting the dotted tool path into CLI path +segments and passing JSON arguments as the final argument: + +```bash +executor call zotero user default zotero_list_collections '{}' +``` + +Use `user.default` by default for local single-user sources unless the user asks +for a different configured source. + +## Safety + +Prefer read-only discovery and query tools unless the user explicitly asks for a +mutation. Ask for confirmation before tools that send messages, delete data, +write notes, change app state, open UI actions on the user's machine, or expose +sensitive local content. + +If Executor pauses for approval, show the approval URL or resume command to the +user and wait for confirmation before continuing. + +Keep normal code work in DevSpace tools. Executor should be used for external +local integrations, not for reading or editing the current workspace.