# Andysparks Word Smithy Word Smithy > Andysparks Word Smithy Word Smithy - Skill: `tomevault-io/andysparks-word-smithy-word-smithy` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/andysparks-word-smithy-word-smithy` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/andysparks-word-smithy-word-smithy/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/andysparks-word-smithy-word-smithy --- # /word-smithy The editorial workshop. One entry point for all writing workflows. ## When Invoked ### Step 1: Load Baseline Context Read the shared config and project config (if present) to discover all available resources. **Shared config location:** `~/.claude/shared/word-smithy/config.md` **Project config location:** `.word-smithy/config.md` in the current project root From each config, load: - **Voice docs** (always loaded, governs all writing) - **Principles docs** (always loaded, governs all writing) Do NOT load references or protocol bodies yet. Those are loaded on demand. ### Step 1b: Discover Existing Writing Context Scan for writing-related context that exists outside word-smithy's own configs: - `CLAUDE.md` in the project root (look for voice, style, tone, or writing sections) - `.claude/rules/` files that mention writing, voice, editorial, or style - `~/.claude/CLAUDE.md` (global rules) - `.cursorrules` or `.github/copilot-instructions.md` (for Cursor/Copilot users) If any are found, acknowledge them: > I found existing writing context in: > - [list files found] > > I'll use these alongside word-smithy's configs. If anything conflicts, your project-level rules win. This ensures word-smithy layers on top of what the user already has rather than replacing it. Users do not need to migrate existing rules into word-smithy's format for them to be respected. ### Step 1c: First-Run Check After loading configs and discovering context, check whether anything meaningful was found. Specifically: 1. Do the `voice` paths in the config(s) point to files that actually exist? 2. Was any writing context discovered in Step 1b (CLAUDE.md, .cursorrules, etc.)? **If no voice file exists AND no external writing context was found**, the user has nothing loaded. Enter onboarding mode instead of proceeding to Step 2. **If a voice file exists** (or meaningful writing context was found in Step 1b), skip onboarding and proceed to Step 2. ### Step 1d: Onboarding (first-run only) When onboarding is triggered, walk the user through creating a minimal voice profile. Don't send them to the guide. Do it here, interactively. Say: > word-smithy is installed, but you don't have a voice profile yet. That's the thing that keeps your AI from sounding like a robot. > > Want to set one up now? Takes about five minutes. If the user says no, proceed to Step 2 with no voice loaded (the skill still works, just without voice guardrails). If the user says yes, walk through these four steps: **1. Collect samples** > Paste 2-3 short pieces of writing you're proud of. Emails, blog posts, social posts, anything. I need to hear what you sound like. Read what they provide. Identify patterns: sentence length habits, vocabulary preferences, structural tendencies, tone. **2. Confirm the patterns** Present what you found: > Here's what I'm noticing in your writing: > - [structural pattern, e.g., "You lead with the problem, not the solution"] > - [sentence pattern, e.g., "Short sentences mixed with longer ones, lots of contractions"] > - [vocabulary pattern, e.g., "Plain words, no jargon"] > > Does that sound right? Anything I'm missing? Let them correct or add. This is collaborative, not prescriptive. **3. Hard bans** > What words or phrases do you never want to see in your writing? Things that make you cringe when AI produces them. > > Common ones people ban: "leverage," "utilize," "Furthermore," "It's worth noting," "It's not X. It's Y." Collect their list. **4. Save the profile** Write the voice profile to `~/.claude/shared/voice-core.md` (or whatever path their config specifies). Use the structure from the [Creating a Voice Profile](guides/creating-a-voice-profile.md) guide. Confirm: > Saved your voice profile to `~/.claude/shared/voice-core.md`. It's loaded now and will be loaded every time you invoke `/word-smithy`. > > This is a living document. Next time something sounds off, tell me and I'll update it. Then proceed to Step 2. **After onboarding, offer next steps (don't block on them):** > Your voice profile is set. Two optional things when you have time: > - **Condense a writing book** you love into an AI reference (see `guides/condensing-a-book.md`) > - **Write a protocol** for a workflow you repeat (see `guides/writing-a-protocol.md`) > > For now, let's write something. ### Step 2: Ask the Question Ask the user: > What are you working on? Wait for a plain-text answer. No menu, no numbered options. ### Step 3: Match Intent to Protocol Scan all protocol paths from both configs (shared + project). For each `.md` file found: 1. Read the YAML frontmatter 2. Check for `name`, `triggers`, and `description` fields 3. If a file lacks these fields, skip it (it is not a word-smithy protocol) Match the user's answer against the `triggers` field of all discovered protocols. Use semantic matching, not exact string matching. The `triggers` field contains representative phrases, not an exhaustive list. **If a match is found:** > Looks like **[protocol name]**. [description] > > Running it. Then load the full protocol file and any files listed in its `loads` field. Walk through the protocol step by step. **If no match is found:** > I don't have a protocol for that yet. Two options: > > 1. **Create one** (I'll help you write a protocol doc for this workflow) > 2. **Just write** (I'll work with voice and principles loaded, no formal process) If the user chooses "just write," proceed with voice + principles as guardrails. This is still better than writing without `/word-smithy` because the baseline context is active. If the user chooses "create one," guide them through writing a new protocol doc: - Ask what the workflow involves - Ask where it should live (shared or project) - Draft the protocol with proper frontmatter - Save it to the appropriate directory - It is immediately available for future `/word-smithy` invocations ### Step 4: Execute Protocol When running a matched protocol: 1. The full protocol document is the process. Follow it step by step. 2. Load files from the `loads` field only when a step references them, not all at once. 3. Voice + principles stay loaded throughout as guardrails. 4. If a protocol references another protocol (e.g., BPP calls the McPhee Loop), discover and load that protocol when the step calls for it. ### Step 5: "Just Write" Fallback When no protocol matched and the user chose to freestyle: 1. Voice core + any project voice profile are active. 2. Principles (if any) are active. 3. Writing references are available on request but not pre-loaded. 4. Apply the voice tests from voice-core.md to any draft before presenting it. ## Cross-Layer Rules - Shared protocols never reference project protocols. - Project protocols can reference shared protocols and shared references. - If a project protocol and shared protocol have overlapping triggers, the project protocol wins. - Voice and principles from both layers are always loaded together. ## Protocol Doc Format For creating new protocol docs, use this frontmatter template: ```yaml --- name: [Human-Readable Name] triggers: [comma-separated phrases that describe when to use this] description: [One-line description shown when confirming the match] layer: [shared or project] loads: - [paths to reference files this protocol needs] --- ``` The body of the protocol is the workflow itself. Write it however makes sense for the process. The skill reads and follows it as instructions. --- > Source: [AndySparks/word-smithy](https://github.com/AndySparks/word-smithy) — distributed by [TomeVault](https://tomevault.io).