apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-07-13 11:22:11 +02:00
Code Issues Projects Releases Packages Wiki Activity

fix(cli): package Claude Desktop skills in one zip

Browse source
This commit is contained in:
Andrey Avtomonov 2026-05-19 13:55:02 +02:00
parent b42f418adc
commit ddabe517e3
4 changed files with 130 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

39
docs-site/content/docs/integrations/agent-clients.mdx
View file

@ -32,7 +32,7 @@ ktx setup --agents --target codex
```
Use `--global` only with `claude-code` or `codex`. Claude Desktop always writes
global Claude Desktop config and generates a project-local plugin package:
global Claude Desktop config and generates a project-local skill ZIP:
```bash
ktx setup --agents --target claude-code --global
@ -85,12 +85,12 @@ before opening the configured agent. If it shows `ktx mcp start --project-dir ..
run that command before using Claude Code, Codex, Cursor, OpenCode, or generic
MCP clients. The same output also prints the matching `ktx mcp stop` command
for when you want to stop MCP later. Claude Desktop uses its own launcher and
only needs a restart.
prints separate skill upload steps.
| Target | Ask data questions with KTX MCP | Adds when agents can manage KTX with CLI |
|--------|------------------------------|---------------------------|
| Claude Code | `.mcp.json`, `.claude/skills/ktx-analytics/SKILL.md` | `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` stdio entry + `.ktx/agents/claude/ktx-plugin.zip` with analytics skill | Adds `skills/ktx/SKILL.md` inside the plugin ZIP |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` stdio entry + `.ktx/agents/claude/ktx-skills.zip` upload | Adds `ktx/SKILL.md` inside the same ZIP |
| Codex | Printed snippet for `~/.codex/config.toml`, `.agents/skills/ktx-analytics/SKILL.md` | `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` |
| Cursor | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` | `.cursor/rules/ktx.mdc` |
| OpenCode | Printed snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` | `.opencode/commands/ktx.md` |
@ -178,8 +178,8 @@ same markdown command definitions.
## Claude Desktop
During setup, select **Claude Desktop** from the agent targets. KTX writes the
MCP server entry directly into Claude Desktop's config and prepares the
Claude Desktop skill package for the analytics workflow:
MCP server entry directly into Claude Desktop's config and prepares uploadable
Claude Desktop skill packages for the KTX workflows:
- `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%AppData%/Claude/claude_desktop_config.json` (Windows) gets an
@ -187,14 +187,20 @@ Claude Desktop skill package for the analytics workflow:
launcher shim at `.ktx/agents/claude/ktx-plugin-runner.sh`. The shim locates
a usable Node.js (Volta, NVM, Homebrew, system) so Claude Desktop can spawn
the server without needing `node` in PATH.
- `.ktx/agents/claude/ktx-plugin.zip` contains the `ktx-analytics` skill (and
the admin `ktx` skill if you choose **Ask data questions + manage KTX with
CLI commands**). This package is generated by KTX setup; no manual plugin
install step is required.
- `.ktx/agents/claude/ktx-skills.zip` contains the `ktx-analytics` skill. If
you choose **Ask data questions + manage KTX with CLI commands**, the same
ZIP also contains the admin `ktx` skill.
After `ktx setup`, restart Claude Desktop so it picks up the new MCP server
entry and bundled KTX skills. No daemon needs to be running — Claude Desktop
spawns the MCP server itself per session.
entry. No daemon needs to be running -- Claude Desktop spawns the MCP server
itself per session.
Upload the generated skill ZIP from Claude Desktop:
1. Open **Customize** > **Skills**.
2. Click **+** > **Create skill** > **Upload a skill**.
3. Upload `.ktx/agents/claude/ktx-skills.zip`.
4. Toggle the uploaded KTX skills on.
Claude Desktop does not introspect local stdio MCP servers, so the per-tool
"Connector"-style UI is not rendered for KTX. The tools are still callable
@ -202,7 +208,8 @@ from any Claude Desktop chat.
If you move the KTX checkout or project directory, rerun `ktx setup --agents`
to refresh the absolute paths in `claude_desktop_config.json` and the launcher
shim, then restart Claude Desktop.
shim, regenerate the skill ZIP, then restart Claude Desktop and upload the new
ZIP.
---
@ -290,8 +297,8 @@ Admin CLI skills call the same KTX CLI commands:
| | Claude Code | Claude Desktop | Cursor | Codex | OpenCode |
|---|---|---|---|---|---|
| MCP tools | Yes | Local stdio via `claude_desktop_config.json` | Yes | Snippet | Snippet |
| Analytics skill | `.claude/skills/ktx-analytics/SKILL.md` | Included in plugin ZIP | `.cursor/rules/ktx-analytics.mdc` | `.agents/skills/ktx-analytics/SKILL.md` | `.opencode/commands/ktx-analytics.md` |
| Admin CLI skills | Optional | Optional in plugin ZIP | Optional (.mdc) | Optional | Optional |
| Analytics skill | `.claude/skills/ktx-analytics/SKILL.md` | Upload `.ktx/agents/claude/ktx-skills.zip` | `.cursor/rules/ktx-analytics.mdc` | `.agents/skills/ktx-analytics/SKILL.md` | `.opencode/commands/ktx-analytics.md` |
| Admin CLI skills | Optional | Optional inside the same ZIP | Optional (.mdc) | Optional | Optional |
| Global install | Yes | Claude Desktop config | No | Yes | No |
| Rule or instruction file | `.claude/rules/ktx.md` | Plugin `SETUP.md` | `.cursor/rules/ktx.mdc` | `.codex/instructions/ktx.md` | `.opencode/commands/ktx.md` |
| Skill file | `.claude/skills/ktx/SKILL.md` | `skills/ktx/SKILL.md` in plugin ZIP | Not separate | `.agents/skills/ktx/SKILL.md` | Not separate |
| Rule or instruction file | `.claude/rules/ktx.md` | Not separate | `.cursor/rules/ktx.mdc` | `.codex/instructions/ktx.md` | `.opencode/commands/ktx.md` |
| Skill file | `.claude/skills/ktx/SKILL.md` | `ktx/SKILL.md` inside `ktx-skills.zip` | Not separate | `.agents/skills/ktx/SKILL.md` | Not separate |