Agent Skill

Agent skill

This page explains the ChemDraft agent skill: a local instruction folder that teaches supported assistants how to use the CLI and MCP server safely.

The folder is skills/chemdraft in the repository. It contains SKILL.md and operation-specific references for setup, drawing, analysis, NMR, files, plugins, art, and recipes. It is not an executable service and does not grant an assistant access to the desktop app. Instead it helps an assistant select the appropriate local MCP tool or CLI command, preserve chemistry, inspect returned warnings, and state scientific limits honestly.

The skill directs an assistant to prefer MCP when available, then use the local CLI when it has a shell. It identifies the checkout from the installed skill’s resolved location rather than assuming the current folder. A copied skill needs an explicit checkout path, so a symlink (macOS) or directory junction (Windows) is the easier installation to keep current.

Install it

On macOS, install a symlink for Claude Code, Codex, or both. Do not overwrite an existing skill directory.

mkdir -p "$HOME/.claude/skills" "$HOME/.codex/skills"
ln -s "<checkout>/skills/chemdraft" "$HOME/.claude/skills/chemdraft"
ln -s "<checkout>/skills/chemdraft" "$HOME/.codex/skills/chemdraft"

On Windows PowerShell, directory junctions avoid needing administrator privileges:

New-Item -ItemType Directory -Force "$HOME\.claude\skills", "$HOME\.codex\skills"
New-Item -ItemType Junction -Path "$HOME\.claude\skills\chemdraft" -Target "<checkout>\skills\chemdraft"
New-Item -ItemType Junction -Path "$HOME\.codex\skills\chemdraft" -Target "<checkout>\skills\chemdraft"

You may instead copy the entire folder, including references, but then update it manually and tell the assistant where the checkout is. The skill assumes the checkout has already been prepared with Node 24, pnpm 10.12.1, dependencies, and the OPSIN runtime if name conversion is needed. See Agent Setup Recipes.

What it asks an assistant to do

The workflow is deliberate: identify the intended molecule including charges, isotopes, stereochemistry, salts, and reaction roles; run the appropriate operation; parse every JSON result; inspect warnings; and visually inspect rendered output before it is used. It cautions that @ and @@ are not literal R/S labels and directs the assistant to use stereochemistry inspection for an R/S or E/Z claim.

For analysis, it retains method metadata, units, status, intervals, and interpretation labels. For NMR, it calls shifts predictions and keeps estimates labelled. If a structure name is ambiguous, it asks for clarification or a systematic name rather than guessing. It does not create an owner’s plugin trust file: the user must choose whether to trust external code.

The skill’s normal CLI form includes pnpm -s --config.shell-emulator=true --dir <checkout> chemdraft <subcommand>. The silent flag preserves JSON Lines; the shell emulator prevents Windows backslash doubling and is safe on both platforms.

Keeping the skill and tools aligned

The skill describes a local capability; installing it does not install dependencies, register MCP, or give a remote chat access to your computer. For an assistant that supports MCP, register the server as well as the skill. The assistant can then use direct structured tool calls for rendering, documents, analysis, names, stereo, NMR, and export. If MCP is absent but the assistant has a local shell, it can use the CLI from the checkout that the installed link resolves to.

When the skill is linked from the checkout, pulling an update updates the instructions and references together with the command modules. A copied folder is useful in environments where links or junctions are unavailable, but it can become stale: replace the complete folder, not just SKILL.md, when updating it. The reference material is part of the skill’s practical contract, particularly the setup and scientific-reporting guidance.

Do not ask an assistant to claim a file or calculation completed merely because it emitted a result. The skill says to require ok: true, retain warnings, and inspect a picture. For a batch, a failure in one job does not erase the successful JSON Lines from other jobs; use the process exit code and every line together. For a result involving a user’s existing document, use the application’s registered command and patch route rather than treating the skill as a way to access private UI state.

See also

• Agent Tools Overview
• MCP Server
• Command-Line CLI
• Agent Setup Recipes