Add developing-with-idfkit discovery skill + cross-client distribution#2
Merged
Merged
Conversation
Bridge the plugin to the version-matched agent references bundled in idfkit 0.13. The new developing-with-idfkit skill discovers the idfkit installed in the user's project and loads its bundled SKILL.md/references — MCP-free, so library-authoring help works without spinning up the server. References are delivered via package discovery (Streamlit-style) rather than the MCP, keeping the "write code with idfkit" and "interact with models via MCP" surfaces separate. Adds the distribution layer that makes the plugin installable across clients: a self-installable Claude Code marketplace manifest, a README install matrix (Claude plugin, npx skills, Copilot, Cursor, Gemini, Codex, raw MCP), AGENTS.md documenting the discovery contract, and a stdlib regression test for discover.py. https://claude.ai/code/session_0121EsSJYijy1gbqZSJ1xFxv
Match idfkit-mcp's MIT license across the family. Adds the LICENSE file and switches the Apache-2.0 declarations in plugin.json, marketplace.json, .codex-plugin/plugin.json, and README to MIT. https://claude.ai/code/session_0121EsSJYijy1gbqZSJ1xFxv
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bridges the plugin to the version-matched agent references bundled in idfkit 0.13, and adds the distribution layer that makes the plugin installable across AI clients. Draws on Streamlit's agent-skills approach, adapted for a plugin (skills + MCP) rather than skills alone.
The architecture decision
References serve the "build software with idfkit" context (writing Python against the library), which is distinct from "interact with IDF models through the MCP" (tool-driven workflows). So reference docs are delivered via package discovery, not the MCP — library-authoring help works without spinning up the server, and the two surfaces stay cleanly separated. (The companion idfkit-mcp PR #73, which routed refs over MCP, is intentionally left unmerged as a result.)
The reference content itself lives inside the idfkit pip package (
idfkit/.agents/skills/developing-with-idfkit/, confirmed shipping in 0.13.0 with 16 topic docs) — not duplicated here, so it never drifts and is always version-matched to the user's pinned idfkit.Changes
New
developing-with-idfkitskillskills/developing-with-idfkit/SKILL.md— routing doc; instructs the agent to run discovery, then read the version-matched bundledSKILL.md/references/.skills/developing-with-idfkit/scripts/discover.py— resolves the user's project interpreter ($VIRTUAL_ENV→.venv→../.venv→ git-root.venv→ conda → pipenv/poetry/pdm/uv → system), imports idfkit, and prints the bundledSKILL.mdpath; actionableERROR:blocks with documented exit codes when idfkit is missing (1), too old (2), no interpreter (3), layout changed (4), or bad arg (5).Distribution layer (the real gap)
README.md— cross-client install matrix: Claude Code full plugin (via marketplace),npx skills, Copilot, Cursor, Gemini, Codex, and raw MCP config..claude-plugin/marketplace.json— makes the repo self-installable as a Claude Code marketplace.AGENTS.md(+ thinCLAUDE.md) — documents the discovery contract and the references-vs-tools boundary.tests/discovery/test_discover.py— 12 stdlib (unittest) tests for the discovery contract..gitignore, plusLICENSE(MIT) with license declarations aligned acrossplugin.json,marketplace.json, and.codex-plugin/plugin.jsonto matchidfkit-mcp.The existing 9 workflow skills, agents, commands, and hooks are left untouched.
Test plan
discover.pyvalidated against real installs: idfkit 0.13.0 → exit 0 (prints bundled SKILL.md), idfkit 0.12.2 → exit 2 (upgrade prompt), empty venv → exit 1 (install advice), bad--project-dir→ exit 5.python -m unittest tests.discovery.test_discover— 12 passed.Apachereferences remain after the MIT switch.npx skills add idfkit/idfkit-plugin -s developing-with-idfkit -gresolves once the repo is on the default branch./plugin marketplace add idfkit/idfkit-plugin+/plugin install idfkit@idfkitin Claude Code.https://claude.ai/code/session_0121EsSJYijy1gbqZSJ1xFxv
Generated by Claude Code