An agent skill and server instructions for using the tools (#175)

CHANGELOG.md

@@ -14,6 +14,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **An agent skill for using the server** (#175). `solidworks-mcp skill
+  install` puts the `solidworks-mcp` skill in Claude Code's skills folder
+  (`--project` or `--dir` for others); it covers the build order, units
+  (and the inputs that take metres), choosing faces and edges, checking
+  results with `verify_model`, recovering from errors, the tools that don't
+  work yet and the known faults. The server also serves it as
+  `skill://solidworks-mcp/SKILL.md` and sends short usage instructions when
+  a client connects. A test fails if the skill names a tool that is gone or
+  recommends one that can't run.
 - **The server takes `--year`**, the installed SolidWorks release it works
   with (`uvx solidworks-mcp-python --year 2026`). It is required for real
   SolidWorks and `setup` writes it into every client entry, from the newest

README.md

@@ -256,6 +256,18 @@ It works only with the circuit-breaker adapter wrapper (the default for real Sol
 
 </details>
 
+## Teach your agent the workflow
+
+Each tool's description says what that tool does. The `solidworks-mcp` skill covers what spans tools: the order to build in (sketch, close it, then the feature), which inputs take millimetres and which take metres, how to pick faces and edges, checking the result with `verify_model`, recovering from errors, and the tools that don't work yet. Install it into Claude Code with:
+
+```powershell
+uvx solidworks-mcp-python skill install
+```
+
+That writes `~/.claude/skills/solidworks-mcp/`. Add `--project` for the current project's `.claude/skills`, or `--dir <folder>` for another agent's skills folder. It writes only that folder and needs no login. Re-run it after an upgrade.
+
+Clients that read MCP resources don't need the install: the server serves the same skill at `skill://solidworks-mcp/SKILL.md`, and points to it in the instructions it sends when a client connects. More: [Agent skill](docs/agents/agent-skill.md).
+
 ## Contributing
 
 `install.ps1` gives you an editable install, so code changes take effect the next time a client starts the server. For the development tools, install the extras:

docs/agents/agent-skill.md

@@ -0,0 +1,51 @@
+# Agent Skill
+
+The server ships a skill, `solidworks-mcp`, for agents that use its tools.
+Each tool's own description says what that tool does
+([Tool Description Standard](tool-description-standard.md)); the skill
+covers what spans tools:
+
+- the order to build in: create or open a document, sketch, close the
+  sketch, then the feature, and `verify_model` at the end;
+- units: inputs are millimetres and degrees, except the few that take metres;
+- choosing planes, faces and edges, and reading what the user selected;
+- checking results, since a tool's success doesn't prove the geometry;
+- reading errors and recovering with `rebuild_model` and `undo`;
+- the tools that can't run yet and the known faults, with workarounds;
+- when to write VBA instead.
+
+The files are `SKILL.md` and four references in
+`src/solidworks_mcp/skills/solidworks-mcp/`, installed with the package.
+
+## Three ways an agent gets it
+
+| Way | What the agent sees | Needs |
+| --- | --- | --- |
+| Server instructions | A short text in the MCP initialize response: start with `get_model_info`, the build order, the unit rule, `verify_model`, and where the skill is | Nothing; every client that shows instructions gets it |
+| MCP resources | `skill://solidworks-mcp/SKILL.md`, a `skill://solidworks-mcp/_manifest` listing its files, and each reference file | A client that reads resources |
+| Installed skill | The skill in the agent's skills folder, loaded when relevant | `solidworks-mcp skill install` |
+
+## Installing it
+
+```powershell
+uvx solidworks-mcp-python skill install            # ~/.claude/skills/solidworks-mcp
+uvx solidworks-mcp-python skill install --project  # .claude/skills in this folder
+uvx solidworks-mcp-python skill install --dir C:\path\to\skills  # another agent
+uvx solidworks-mcp-python skill install --dry-run  # show, write nothing
+```
+
+The command copies the packaged files into `<folder>/solidworks-mcp/`,
+replacing older copies of them and leaving any other file there alone. It
+reads nothing but the packaged skill (no client config, no other skill) and
+needs no network or login. Re-run it after upgrading the server.
+
+## Keeping it true
+
+`tests/integration/test_skill_content.py` fails when the skill or the
+instructions name a tool that isn't registered, or send an agent to a tool
+that can't run yet (those may be named only in the limits reference, which
+lists them). When a fault in `openspec/queue.md` item 10 is fixed, remove
+it from `references/errors-and-limits.md` in the same change.
+
+For changing the server's COM code, the contributor reference is
+[COM API Pitfalls](com-api-pitfalls.md).

docs/agents/com-api-pitfalls.md

@@ -10,6 +10,11 @@ Every entry below caused a real runtime failure that required hours to diagnose.
     They are the delta between "what the documentation says" and "what actually works"
     under pywin32 late-binding on SW 2025/2026.
 
+!!! note "Using the server, not changing it?"
+    This page is for changing the COM code. For how an agent should *use* the
+    tools (build order, units, selection, known limits), see the
+    [Agent Skill](agent-skill.md).
+
 ---
 
 ## 1. `SelectByID2` — `Callout` must be `VT_DISPATCH` null, not `None`

mkdocs.yml

@@ -68,6 +68,7 @@ nav:
       - Worked Examples: agents/worked-examples.md
       - Prompt-Driven Design: agents/prompt-driven-design.md
       - Tool Description Standard: agents/tool-description-standard.md
+      - Agent Skill: agents/agent-skill.md
       - Prompting Tutorials: agents/prompting-tutorials.md
       - COM API Pitfalls (LLM Agent Guide): agents/com-api-pitfalls.md
   - Planning:

openspec/changes/agent-skill-and-instructions/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-04

openspec/changes/agent-skill-and-instructions/design.md

@@ -0,0 +1,126 @@
+## Context
+
+See proposal.md for why. Current state:
+
+- `server.py` builds `FastMCP("SolidWorks MCP Server", version=...)` with no
+  `instructions` and registers no resources; tools come from
+  `tools.register_tools`.
+- `cli_main` starts the server, except `solidworks-mcp setup ...`, which hands
+  off to the Typer app in `setup/cli.py`.
+- FastMCP 3.4.9 (installed) has
+  `fastmcp.server.providers.skills.SkillProvider(skill_path)`, which serves
+  one skill folder as `skill://<name>/SKILL.md`, `skill://<name>/_manifest`
+  and its other files, added with `mcp.add_provider(...)`. The
+  `SkillCatalogProvider` and `Skill` classes the user's notes mention are
+  FastMCP 4.x and are not used.
+- The wheel packages `src/solidworks_mcp`, so files placed under it ship.
+- Tool descriptions (#82) already say what each tool does; the skill must
+  not repeat them.
+
+## Goals / Non-Goals
+
+**Goals:** one source of guidance, in the package, reachable three ways
+(server instructions, `skill://` resources, an installed skill), and a test
+that fails when it names a tool that is gone or recommends one that can't
+run.
+
+**Non-Goals:**
+
+- Fixing the faults the skill warns about (queue item 10).
+- Per-client install logic beyond a skills folder (no editing of client
+  configs; `solidworks-mcp setup` stays as it is).
+- Contributor guidance: `com-api-pitfalls.md` stays the COM reference.
+
+## Decisions
+
+### The skill lives in the package, at `src/solidworks_mcp/skills/solidworks-mcp/`
+
+Rather than `skills/solidworks-mcp/` at the repo root (the issue's
+suggestion). Inside the package it ships in the wheel, so `uvx` and pip
+installs can serve and install it without the repo; at the root it would need
+extra packaging config and would be missing from installs. The
+`skills/` folder name keeps the layout the issue describes.
+
+### Layout: `SKILL.md` plus four reference files
+
+- `SKILL.md`: when to use it, the build order, the unit rule, the
+  read-back rule, and a map to the references (target: about 150 lines).
+- `references/workflows.md`: part, assembly and drawing walk-throughs as
+  tool sequences, with the checks between steps.
+- `references/selection-and-units.md`: planes, faces, edges; every input
+  that takes metres (`measure_entities`, the `edge_names` point specs of
+  `add_fillet`/`add_chamfer`) against the rest in mm.
+- `references/errors-and-limits.md`: reading an error (`error_type`,
+  `hint`), `rebuild_model` and `undo`, the tools that can't run yet, and
+  the known faults from queue item 10 with their workarounds.
+- `references/vba-fallback.md`: when to use the VBA generation tools and
+  `execute_macro`, and when not to.
+
+This keeps `SKILL.md` short (it is read whole), with detail loaded only when
+needed, which is how both Claude Code and the `skill://` manifest are meant
+to work.
+
+### Serve it with `SkillProvider`, supporting files as a template
+
+`mcp.add_provider(SkillProvider(path))` where the server builds its
+`FastMCP` instance, not in `setup()` (which connects to SolidWorks first), with the
+default `supporting_files="template"`: `list_resources` shows `SKILL.md` and
+the manifest, and the reference files are read through the manifest. This
+keeps the resource list short. Alternative, `"resources"` (every file
+listed): rejected, it lengthens the list every client loads.
+
+### Instructions: a constant next to the skill, at most 1500 characters
+
+A module constant (`skills.SERVER_INSTRUCTIONS`) passed to `FastMCP(...,
+instructions=...)`. It holds only the rules a session can't do without (see
+the spec) and points to the skill. Alternative, generating it from
+`SKILL.md`: rejected; the two have different jobs and lengths.
+
+### `solidworks-mcp skill install` as its own small Typer app
+
+`cli_main` routes `skill` the way it routes `setup`. The command takes
+`--project`, `--dir PATH` and `--dry-run`, and copies the packaged files from
+the package folder, overwriting only files it ships. It never deletes,
+never follows the folder outside the target, and reads nothing but the
+packaged skill, so it can't touch other users' or tools' files. It needs no
+network or token.
+
+Alternatives: an option on `setup` (rejected: `setup` is an interactive flow
+about client configs; mixing the two would make `--yes` also write skills),
+or only documenting a manual copy (rejected: the issue asks for one
+command). `setup` prints a one-line hint about `skill install` at the end;
+that is the only change to it.
+
+### A test keeps the skill true
+
+`tests/integration/test_skill_content.py` (it spans the skill, the tools
+and the instructions, so it is cross-module) parses tool names from
+the skill files and the instructions (backticked names that match the
+registered-tool pattern) and checks each is registered, and that no tool the
+skill's build steps recommend is one that can't run (the "Not available yet"
+sentence in its description). A fault fixed later must also be removed from
+`errors-and-limits.md`: the queue's item-10 entry says so.
+
+## Risks / Trade-offs
+
+- [The skill drifts from the tools as they change] → the name test above,
+  and the queue note that fixing a fault edits the skill.
+- [Clients that ignore `instructions` and resources] → the installed skill
+  covers them; the README says how.
+- [Codex's skills folder may differ by version] → `--dir` takes any folder;
+  the README names Claude Code's folder and shows `--dir` for others rather
+  than guessing a path.
+- [The measured run depends on live SolidWorks and an agent run] → it is the
+  last task, run by the user with `live_demo.ps1`-style permission, and does
+  not block merging the skill.
+
+## Migration Plan
+
+Additive. Rollback is removing the provider and instructions line; installed
+skills are plain files users can delete.
+
+## Open Questions
+
+- Which demo prompt the measurement uses: the bracket demo (#147, queue item
+  6, may be narrowed) or the monitor-stand demo already in `docs/demos/`.
+  Either fits the task; it is chosen when the live run is scheduled.

openspec/changes/agent-skill-and-instructions/proposal.md

@@ -0,0 +1,65 @@
+## Why
+
+Agents call this server's tools without knowing how SolidWorks work goes:
+that a feature needs a sketch closed first, which tools take millimetres and
+which take metres, that a modelling tool's success does not prove the
+geometry is right, or which tools can't run yet. The guidance that exists
+(`docs/agents/com-api-pitfalls.md`, `.claude/skills/`) is written for
+contributors changing the COM code, not for people using the server, and an
+agent only sees it if someone pastes it in. Issue #175 asks for a skill users
+install into their agent; the tool descriptions (#82, now done) cover each
+tool, so what is missing is the guidance that spans tools.
+
+## What Changes
+
+- **A usage skill** for agents that drive the server: `SKILL.md` plus a few
+  reference files, shipped inside the Python package so every install has
+  it. It covers the build order (part, sketch, `exit_sketch`, feature,
+  `verify_model`), units (mm in, with the named exceptions that take metres),
+  planes and face/edge selection, reading back after every change, recovering
+  from errors (`rebuild_model`, `undo`), the tools that can't run yet and the
+  known faults, and when to fall back to VBA generation. Sourced from the
+  tool code, the description standard, `com-api-pitfalls.md` and
+  `openspec/queue.md`.
+- **The server serves the skill** as MCP resources (`skill://solidworks-mcp/SKILL.md`
+  and its files), so a client that reads resources gets it with no install.
+- **Server instructions**: a short `instructions` text sent at connection
+  with the few rules every session needs, pointing to the skill for the rest.
+- **One-command install**: `solidworks-mcp skill install` copies the skill
+  into an agent's skills folder (Claude Code's user or project folder by
+  default, or any folder given). It writes only its own folder and reads no
+  other file.
+- **README and docs**: the install command and what the skill covers.
+- **Measured**: the demo prompt run with and without the skill on real
+  SolidWorks, and the difference recorded (live run, with the user's
+  permission).
+
+No adapter or COM code changes. Nothing is removed.
+
+## Capabilities
+
+### New Capabilities
+
+- `agents/usage-skill`: the skill's content and the rules that keep it true
+  (every tool it names exists and is described as the tool behaves), how the
+  server serves it, and how `solidworks-mcp skill install` places it.
+- `agents/server-instructions`: the `instructions` text the server sends at
+  connection.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- New: `src/solidworks_mcp/skills/solidworks-mcp/` (the skill files),
+  `src/solidworks_mcp/skills/` code to serve and install it, a `skill`
+  subcommand in `cli_main` (`server.py`).
+- Changed: `server.py` passes `instructions` to `FastMCP` and adds the
+  skill provider; README and `docs/` gain the install section.
+- Packaging: the skill files ship in the wheel (they live under
+  `src/solidworks_mcp`, which the wheel already includes).
+- Depends on FastMCP 3.4.9's `SkillProvider`, already installed; no new
+  dependency.
+- No change to `pywin32_adapter.py`, `base.py` or `mock_adapter.py`.
+- GitHub issue: #175.

openspec/changes/agent-skill-and-instructions/specs/agents/server-instructions/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: The server sends short usage instructions at connection
+
+The server SHALL send an `instructions` text in its MCP initialize response.
+It SHALL be at most 1500 characters and SHALL say:
+
+- to call `get_model_info` (or `list_open_documents`) first, to see what is
+  open;
+- the build order: `create_sketch`, draw, `exit_sketch`, then the feature;
+- that inputs are millimetres and degrees unless a field says otherwise;
+- to finish a build with `verify_model`, since a tool's success does not
+  prove the geometry;
+- that tools whose description starts "Not available yet" return
+  `not_supported`;
+- where the full guidance is: the `skill://solidworks-mcp/SKILL.md` resource.
+
+Every tool it names SHALL be a registered tool.
+
+#### Scenario: A client connects
+
+- **WHEN** an MCP client initializes a session with the server
+- **THEN** the response carries the instructions text
+- **AND** it names `skill://solidworks-mcp/SKILL.md`
+
+#### Scenario: The instructions name a removed tool
+
+- **WHEN** a tool named in the instructions is no longer registered
+- **THEN** the test suite fails, naming the tool