Skip to main content

Install the Claude Code skill

Outcome. Your project carries a skill file that teaches a coding agent how Mailwoman is set up, so it stops guessing at the parts that are easy to get wrong.

The two things agents reliably get wrong here are the same two things people get wrong: they debug a parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. failure that doctor would have explained in one line, and they treat the raw confidence score as calibrated. The skill front-loads both.

Prerequisites​

  • mailwoman 8.7.0 or later installed, globally or in the project.
  • A project that reads .claude/skills/. Claude Code does; the file is plain Markdown with YAML frontmatter, so another agent runner can read it too.

1. Install it​

Run this from the project root:

npx mailwoman skill install
✓ mailwoman skill: installed at /tmp/mw-skill-aVjb/.claude/skills/mailwoman
PASS (1/1 checks)

One file lands:

find . -type f
./.claude/skills/mailwoman/SKILL.md

Commit it. It is 103 lines of Markdown and it belongs in the repository, next to the other things that tell a contributor how this project works.

2. Put it somewhere else, if you need to​

--dest writes to a different root and leaves the working directory untouched:

npx mailwoman skill install --dest ../shared-agent-config
✓ mailwoman skill: installed at /tmp/mw-skill-dest-iV0v/.claude/skills/mailwoman
PASS (1/1 checks)

3. Re-run it after an upgrade​

The command is a clean-slate reinstall, not a merge. It removes the destination skill directory and copies the shipped one in, so a file that an older release shipped and a newer one dropped does not linger:

npx mailwoman skill install
✓ mailwoman skill: installed at /tmp/mw-skill-aVjb/.claude/skills/mailwoman
PASS (1/1 checks)

Exit code 0, same as the first run. Re-run it whenever you upgrade mailwoman.

4. Know what it teaches​

Five sections, and each one exists because it is a place agents go wrong:

  • Run doctor first. What the seven checks are, that exit code 0 means the two core checks passed, and that a red mark on a data layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. is a reported gap with a fix: line rather than a failure.
  • Parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates.. The CLI form and the library form, the tree shape, and a pointer to the ComponentTag type in @mailwoman/core/types for the tag vocabularyvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it.. It points at the shipped type rather than at a documentation URL, because the skill installs into projects that may be offline.
  • Geocode. mailwoman data pull candidate as the whole setup — the file lands where every entry point looks — plus the measured case for leaving that default alone, and the one trap in the override.
  • Filing a bug. The five things a report needs, covered on Report a parsing bug.
  • Installing this skill in a new project. So an agent that has read it once can set up the next project.

One correction it carries that is worth knowing about yourself: confidence is the modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.''s raw scorelogitA raw, unnormalized per-label score the model outputs before softmax. Priors and biases are added in logit space, then softmax turns logits into probabilities. and is not calibrated by default. Wire createCalibrator from @mailwoman/core/decoder before routing on it. Tune confidence thresholds is the long version.

Verify​

Read the frontmatter back. The description is what a client matches against to decide whether to load the skill, so an empty or truncated file is the failure mode worth checking for:

head -4 .claude/skills/mailwoman/SKILL.md
---
name: mailwoman
description: Use when a project has installed mailwoman (or is deciding whether to) and you need to parse, geocode, or validate postal addresses — diagnosing a broken install, wiring the CLI or the library, setting up the gazetteer, or filing a precise bug report.
---

Limits​

  • The skill is not the MCP server. It teaches an agent how to use Mailwoman from the shell and from code. It gives the agent no tools. If you want the agent to parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. and geocode directly, add the MCP server as well — they compose, and neither replaces the other.
  • It is a snapshot of the shipped release. The skill file is copied out of the installed package, so it describes the version you have. Re-run the installer after an upgrade.
  • Nothing keeps a project's copy current. There is no check that fails when the committed skill drifts from the installed package. Re-running the installer is the whole mechanism.