# Wordsmith

> Smart wordlist generator and cleaner. Use when the user asks to create, build, expand, or clean a wordlist / password dictionary / .txt list of words — from a natural-language description, a seed .txt file, or SecLists files — with control over output size. Also for merging/deduping/cleaning existing lists before use with hashcat, aircrack, crunch-style workflows, or any tool that consumes wordlists. Trigger phrases: "make me a wordlist", "generate a dictionary", "expand these words", "clean this list", "dedupe this txt", "wordlist for hashcat/aircrack", "top N passwords".

- Skill: `kimiguel/wordsmith` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kimiguel/wordsmith`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kimiguel/wordsmith/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KiMiGuel (https://skillmd.com/u/kimiguel)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kimiguel/wordsmith

---


# Wordlist Smith

Generate smart, size-controlled wordlists and clean existing ones.

## Core Principle: Smart, Not Mechanical

Never generate dumb sequential permutations (`00000`, `00001`, `00002`...). That is what crunch does; this skill exists to do better. Generate words ranked by real-world likelihood:

- **Semantic expansion:** from seed words, generate related words in the same domain (teams, names, places, slang, brands, cultural terms).
- **Locale awareness:** for Spanish/Mexican targets, include ñ/á/é variants, common name patterns, LADA/city terms, fútbol clubs, date formats (DDMMYYYY), typical combos (`chivas2024`, `tijuana123`).
- **Ranked output:** most probable words first, not alphabetical.

## Common Human Password Habits (apply as mutations)

These are what real people do — use them as the mutation vocabulary:

1. **Leetspeak swaps:** a→4/@, e→3, i→1/!, o→0, s→$/5, t→7, b→8, g→9
2. **Suffix padding:** 123, 1234, !, !!, 01, birth year, current year
3. **First-letter capitalization only:** `Password` (the lazy complexity trick)
4. **Name + year:** `juan1995`, `maria2024`
5. **Word + word combos:** `perro_negro`, `chivasgana`
6. **Keyboard walks:** `qwerty`, `asdf`, `1qaz2wsx`
7. **Reversed words:** `drowssap`
8. **Doubled words:** `abcabc`, `mexicomexico`

Apply mutations selectively to likely candidates — never explode every mutation across every word (that recreates the dumb-permutation problem with extra steps).

## User-Specified Substitutions

If the user asks to replace specific letters with numbers/chars (e.g. "replace all e with 3"), use the cleaner's deterministic swap instead of hand-editing lines:

```bash
# keep originals AND emit swapped variants
python3 scripts/clean_wordlist.py INPUT -o OUTPUT --swap a=4,e=3

# emit ONLY swapped variants
python3 scripts/clean_wordlist.py INPUT -o OUTPUT --swap-all a=4,e=3
```

Swaps are case-insensitive (`a=4` also rewrites `A`). Always pass the user's exact mapping — do not substitute the default leet table unless the user just says "leetspeak it" without specifics.

## Input Modes

1. **Natural language:** "top 20 most used Mexican passwords, expand to 1000 similar words" → generate seeds, expand semantically, cap size.
2. **Seed file:** user provides a .txt → clean it first (below), then expand if asked.
3. **SecLists:** user points at a SecLists path (Kali: `/usr/share/seclists/`) → read, clean, expand/combine as requested.
4. **Raw pasted text:** user pastes content copied from a website/article (numbered rankings, comma-separated blobs, words in prose). Save the paste to a temp .txt, then:
   - Numbered/listed format (`1.`, `3)`, `- `) → run the cleaner as-is; it strips ranking prefixes and surrounding quotes/punctuation automatically.
   - Comma/space-separated blob → run the cleaner with `--split`.
   - Words embedded in full article prose → extract the candidate words yourself first, write them to a .txt, then clean.

## Size Control (Hard Rule)

The user's requested count is a **hard cap**. "Make 1000 words" = exactly 1000, never 1001. If expansion would exceed the cap, keep the highest-likelihood words. If it falls short, say so and ask before padding.

## Cleaning Existing Lists

Always run the bundled cleaner on any user-fed .txt before processing:

```bash
python3 scripts/clean_wordlist.py INPUT -o OUTPUT [--max N] [--min-len N] [--max-len N]
```

It handles:
- **Encoding:** detects and converts UTF-8 BOM, UTF-16, cp1252, latin-1 → clean UTF-8 output
- **Dedupe:** exact duplicates removed, original order preserved
- **Ghost characters:** zero-width (U+200B/FEFF), control chars, stray spaces, non-printables stripped
- **Blanks/length filters:** empty lines dropped; optional min/max length

Check the stderr report (`kept=X dups=Y`) and relay it to the user in one line.

## Output

- Plain .txt, one word per line, UTF-8, no BOM, trailing newline.
- **Default save location:** `/home/kali/Desktop/wordlists/` on Kali (create it with `mkdir -p` if missing). If the user names a different location for a specific request, that overrides the default.
- Default filename from the task (e.g. `mexico_top1000.txt`).
- Report in one line: total words, cap applied, save path. No filler.