docs: add a skill for working in this repo

[ciaransweet]

The consuming half of developmentseed/mcp-toolsets-runtime#137. The runtime ships the authoring skill; this is the thin one for what only this repo knows.

What it covers

.claude/skills/deploying-mcp-toolsets/SKILL.md, 111 lines:

• what a change redeploys: one toolset, all of them, or nothing
• deleting a toolset directory is a teardown, so use ./scripts/remove-toolset
• the infra/ templates behind the scaffold's deployment config, and the naming the deploy relies on
• the checks: this repo's scripts/, and the views build a toolset with a UI needs first
• the conventions CI enforces and nothing else states
• the target markers, including that scripts/prune-target takes its root from where the script lives, and the AWS synthesis rule

Writing the tools is not here. That belongs to the runtime's own skill, which ships in the wheel; uv run mcp-toolset skill prints its path. Per #44 this repo reads it there rather than vendoring a copy.

Each thing is said once

The runtime's skill already carries the six runtime module names and the "owns no runtime code" rule, the scaffold walkthrough, what the contract sweep asserts, the serve-and-call block, and the async rule. All of that is out of this one.

CLAUDE.md carried the same material a third time, and its copy of the AWS rule had already drifted from the skill's wording. It goes from 108 lines to 51: a pointer to both skills, plus what must hold even when neither is loaded — no runtime code here, never read .env, a merged directory deletion is a teardown, prune-target's root, and no local kubectl. The two destructive ones stay in CLAUDE.md deliberately rather than relying on a skill being loaded.

So the repo ends up with less prose than it started with, which is the point of #30. Between this skill and the runtime's, that issue's ask — help an agent add a toolset or port a codebase into one — is answered.

It prunes correctly

The skill carries target markers, so a pruned instance does not keep prose about the target it dropped. Verified on copies in both directions:

Pruned	Result
aws removed	the shared section and the AWS rule go, the kubectl rule stays
k8s removed	the shared section goes, the AWS rule stays unwrapped, the kubectl rule goes

No markers survive either. Its own section about markers names none literally, since the prune matches the string anywhere in a line, so it does not need adding to MARKER_LITERATURE. Now that both files are tracked, test_markers_are_balanced_everywhere and test_a_pruned_repo_keeps_no_markers cover them without changes.

Test

tests/test_skill_doc.py, 25 lines, two checks that catch drift: the frontmatter carries a description an agent can match on, and every scripts/ path the skill names exists. A skill named wrong fails the first time it is invoked, and test_deployment_config.py already covers the pyproject key.

52 tests pass, lint clean, rebased past #44.

Note

While checking the prune behaviour I ran scripts/prune-target expecting it to act on a copy. It takes its root from where the script lives, not the working directory, so it pruned this working tree instead. Tracked files came back with git checkout; the then-untracked skill did not and was rewritten. That trap is now written into both the skill and CLAUDE.md.

🤖 Generated with Claude Code

[ciaransweet]

Rewritten against the runtime's own skill, which now ships in the wheel (uv run mcp-toolset skill prints its path).

What went, and where it already lives

Cut from this skill	Already in
the six runtime module names, "this repo owns no runtime code"	the runtime's skill, rule 1
the scaffold walkthrough and what mcp-toolset new writes	the runtime's skill, rule 3 and step 1
what the contract sweep asserts	the runtime's skill, step 2
the mcp-serve-local / mcp-cli list / mcp-cli call block	the runtime's skill, step 5
"tools that do I/O are async def"	the runtime's skill, step 2

153 lines to 111. What is left is what only this repo knows: what a change redeploys, that a merged deletion is a teardown, the infra/ templates behind the scaffold's deployment config, the naming the deploy relies on, the two CI conventions, the markers with prune-target's root trap, and the AWS synthesis rule.

CLAUDE.md, 108 lines to 51. It carried the same material a third time, and its copy of the AWS rule had already drifted from the skill's wording. It is now a pointer to both skills plus what must hold even when neither is loaded: no runtime code here, never read .env, a merged directory deletion is a teardown, prune-target's root, and no local kubectl.

The test, 49 lines to 25. Kept the two checks that catch drift: a description an agent can match on, and every scripts/ path the skill names existing. Dropped the name-matches-directory check, which fails visibly the first time the skill is invoked, and the assertion on a prose string, since test_deployment_config.py already covers the pyproject key.

The --install line is gone with the rest: per #44 this repo reads the runtime's skill from the wheel rather than vendoring a copy.

52 tests pass, lint clean, markers still balanced and both prune directions still leave none.

[ciaransweet]

Also rebased onto main past #44, whose CLAUDE.md line about reading the runtime's skill from the wheel is now the pointer section at the top of the rewritten file.