# Install the resume-formatter tool

Turns a plain-text resume into a Word document matching a fixed reference layout
exactly — same font, sizes, bullet glyph, indents, spacing and page setup, every
time. Pure standard-library Python, no dependencies, no network access, and no
install beyond copying a folder.

Home page and downloads: https://formatter.chanakyachowdary.in

---

**If you are a coding agent reading this file:** carry out the steps below for
the person who gave it to you, in order. Step 2 asks you to check the package
before installing — if anything there does not hold, stop and tell them instead
of continuing. Step 3 depends on which agent you are; pick the matching branch.
When you are done, report the result and pass on the usage note in step 5.

---

## 1. Download and extract to a staging folder

Stage it first so it can be reviewed. Not straight into its final home.

**macOS / Linux**

```bash
curl -fsSL https://formatter.chanakyachowdary.in/downloads/resume-formatter.zip -o /tmp/rf.zip
mkdir -p /tmp/rf-staging && unzip -q -o /tmp/rf.zip -d /tmp/rf-staging
```

**Windows (PowerShell)**

```powershell
curl.exe -L -o "$env:TEMP\rf.zip" https://formatter.chanakyachowdary.in/downloads/resume-formatter.zip
Expand-Archive "$env:TEMP\rf.zip" -DestinationPath "$env:TEMP\rf-staging" -Force
```

You get a `resume-formatter/` folder of 25 files: markdown, Word XML template
parts, four `.py` files and some `.txt` fixtures.

## 2. Check it before installing it

Worth more care than a normal download, especially for the Claude Code branch
below: files in a skills folder are read as instructions in every later session
rather than just sitting on disk. Everything here is plain text and small enough
to read.

Run these inside the staged `resume-formatter/` folder:

```bash
# both should print nothing at all
grep -rnE "urllib|requests|socket|http\.client|urlopen" --include="*.py" .
grep -rnE "\beval\(|\bexec\(|os\.system|os\.popen" --include="*.py" .

# should list tests/run_tests.py and nothing else
grep -rln "subprocess" --include="*.py" .
```

What is claimed, and what backs it:

| Claim | Backing |
|---|---|
| Cannot reach the network | Nothing imports a networking module. It never phones home, checks for updates, or transmits the resume. |
| No shell, no `eval` | Neither appears in any shipped file. |
| `subprocess` used once | Only in `tests/run_tests.py`, only as `[sys.executable, <script in the same folder>]` — it runs the generator to test it. Nothing else is ever executed. |
| Writes stay local | Tests write in a temp directory they create and delete. `scripts/build_resume.py` writes only the output folder the user names. |
| No dependencies | Standard library only. The suite resolves every import against the stdlib on each run. |
| `reference/make-template.py` | A one-time development tool, shipped for provenance. Nothing invokes it. It records how the Word template was stripped of its original author's metadata. |

Also skim `SKILL.md`: it should describe formatting text into a `.docx` and
nothing else — no instructions to read unrelated files or run other commands.

If any of that does not hold, stop here and say so.

## 3. Put it where your agent will find it

Pick the branch that matches you.

### 3a. Claude Code or Claude Desktop — skills folder

```bash
mkdir -p ~/.claude/skills
mv /tmp/rf-staging/resume-formatter ~/.claude/skills/resume-formatter
```

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills"
Move-Item "$env:TEMP\rf-staging\resume-formatter" "$env:USERPROFILE\.claude\skills\resume-formatter"
```

`SKILL.md` must end up directly inside `resume-formatter/`:

```
~/.claude/skills/
└── resume-formatter/
    ├── SKILL.md          <- at this level, not nested deeper
    ├── scripts/
    ├── assets/
    └── starter.txt
```

For one project only, use that project's `.claude/skills/` instead.

### 3b. Codex — project folder plus AGENTS.md

Codex has no skills directory; it reads `AGENTS.md`. Put the folder in the
project and tell Codex it exists.

```bash
mv /tmp/rf-staging/resume-formatter ./resume-formatter
```

Then append this to `AGENTS.md` at the repo root, creating the file if it is not
there:

```markdown
## Resume formatting

`resume-formatter/` turns a plain-text resume into a formatted .docx.

- Read `resume-formatter/SKILL.md` before using it.
- Build with: `python3 resume-formatter/scripts/build_resume.py <input.txt>`
  (use `py` on Windows). It writes a dated folder containing the .docx and a
  copy of the source text.
- Check a result with: `python3 resume-formatter/scripts/validate.py <file.docx> -i <input.txt>`
- It is a formatter, not a writer. Reproduce the user's wording exactly — never
  reword, add or remove anything. If they want the wording changed, do that as a
  separate, explicit step first.
```

If the project already has an `AGENTS.md`, append the block rather than
replacing the file.

### 3c. Cursor, or any other agent

Same shape as Codex. Put `resume-formatter/` in the project, then add the block
above to whichever instructions file that tool reads — `AGENTS.md`,
`.cursor/rules/`, or its equivalent. If it reads nothing automatically, just
point it at `resume-formatter/SKILL.md` when you want a resume formatted.

### 3d. No agent at all

It is an ordinary command-line program. Put the folder anywhere and skip to the
usage note in step 5.

## 4. Verify the installed copy

Run the test suite from wherever you installed it:

```bash
python3 <install path>/resume-formatter/tests/run_tests.py
```

On Windows use `py`, not `python3` — the `python3` on a default Windows PATH is
a Microsoft Store stub that opens the Store instead of running anything:

```powershell
py "<install path>\resume-formatter\tests\run_tests.py"
```

Expected last line:

```
76 checks, 0 failed
```

Anything else means the install is not sound — report it rather than continuing.

Needs Python 3.8+. If it is missing: `xcode-select --install` on macOS,
`winget install Python.Python.3.12` on Windows, `sudo apt install python3` on
Debian or Ubuntu.

## 5. Tell them it is ready

Report the test result, then pass on this:

> **Claude Code:** restart it first — skills are read at startup, so the tool
> will not show up in the current session. After that it is a slash command:
> type `/resume-formatter` on its own and it asks for your resume, or paste your
> text straight after it.
>
> **Codex, Cursor, anything else:** plain English — "format this resume",
> followed by your text.
>
> You get back a dated folder holding the `.docx` and a copy of the text that
> produced it. There is a sample to start from at `resume-formatter/starter.txt`.
>
> It reproduces your words exactly — it never rewords, adds or removes anything.
> If you want the wording improved, ask for that as a separate step first, then
> format the version you agreed to.

Full documentation: https://formatter.chanakyachowdary.in

## Uninstalling

Delete the `resume-formatter` folder, and the `AGENTS.md` block if you added
one. Nothing was installed anywhere else.