# Setup

This repo is a written guide (markdown only, no application code) that
teaches you the Claude Code "skills" format and ships one working example
skill you can copy and try. There is nothing to build or run as a server —
"installing" here means: have Claude Code, get this repo onto your machine,
and copy the example skill into the right folder.

## What you need

| Requirement | Why | Have it already? |
|---|---|---|
| Claude Code (any recent version) | Skills are a Claude Code feature — nothing in this repo does anything without it | Run `claude --version` |
| Git (any recent version) | To clone this repo | Run `git --version` |
| Node.js + npm (any recent version) | Only needed if you use the `npx skills add <owner>/<repo>` shared-install command shown in README.md. Not needed if you copy the example skill by hand (the method these notes use below) | Run `node --version` |
| Text editor | To read/edit `SKILL.md` files — markdown with YAML frontmatter | Any editor works |

**NOT needed:** Docker, any account or signup, any paid API key, a GPU, Python. This repo has no `.env` file to fill in — the `.env` / `.env.*` lines in `.gitignore` are generic boilerplate, not something this repo actually uses.

## Install, step by step

1. **Install Homebrew** (macOS, skip if you already have it):
   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
   Installs the Homebrew package manager.
   Check it worked: `brew --version` → prints a version like `Homebrew 4.x.x`.

2. **Install Git** (skip if `git --version` already works):
   - macOS: `brew install git`
   - Windows: install [Git for Windows](https://git-scm.com/download/win)
   - Linux (Debian/Ubuntu): `sudo apt install git`
   Check it worked: `git --version` → prints a version like `git version 2.x.x`.

3. **Install Claude Code** (skip if `claude --version` already works):
   - macOS/Linux: `curl -fsSL https://claude.ai/install.sh | bash`
   - Any OS with Node.js already installed: `npm install -g @anthropic-ai/claude-code`
   Installs the `claude` CLI that skills run inside of.
   Check it worked: `claude --version` → prints a version number.

4. **Clone this repo:**
   ```bash
   git clone <this-repo-url> skills-guide
   cd skills-guide
   ```
   Check it worked: `ls` → shows `README.md`, `SETUP.md`, and `examples/`.

5. **(Optional) Install Node.js** — only if you plan to use the `npx skills add` install method from README.md instead of copying files by hand:
   - macOS: `brew install node`
   - Windows/Linux: install from [nodejs.org](https://nodejs.org)
   Check it worked: `node --version` and `npx --version` both print version numbers.

6. **Copy the example skill into your Claude Code skills folder.** Pick global (available in every project) or per-project (checked into one repo's `.claude/`):
   - Global:
     ```bash
     mkdir -p ~/.claude/skills/readme-clarity-review
     cp examples/hello-skill/SKILL.md ~/.claude/skills/readme-clarity-review/SKILL.md
     ```
   - Per-project (run from inside the target project):
     ```bash
     mkdir -p .claude/skills/readme-clarity-review
     cp /path/to/skills-guide/examples/hello-skill/SKILL.md .claude/skills/readme-clarity-review/SKILL.md
     ```
   Check it worked: `cat ~/.claude/skills/readme-clarity-review/SKILL.md` (or the project path) shows the `name: readme-clarity-review` frontmatter.

## Configure

Nothing to configure. This repo has no environment variables, no config files, and no API keys — it is markdown only.

## Run it

From any project directory (ideally one with a `README.md` in it), run:

```bash
claude
```

Then ask: `review my README for clarity`

Success looks like: Claude Code follows the numbered steps from the `readme-clarity-review` skill — reading the full README, checking for the required sections, and reporting findings as a list of `section / issue / fix` — instead of giving a generic, unstructured response. That confirms the skill loaded and triggered correctly.

## Troubleshooting

1. **`claude: command not found`** — Claude Code isn't installed or isn't on your `PATH`. Re-run the install command in step 3 above, then open a new terminal window.
2. **Claude never uses the skill (generic response instead of the numbered checklist behavior)** — the folder name, the `name:` field in the frontmatter, and the file location must all line up: `~/.claude/skills/readme-clarity-review/SKILL.md` (or `.claude/skills/readme-clarity-review/SKILL.md` for a project). Check for typos in the path and confirm the file actually copied with `cat`.
3. **`npx skills add ...` fails or errors about missing `npx`** — Node.js/npm isn't installed. Do step 5 above, or skip that method entirely and copy the skill folder by hand as shown in step 6.