# AcademicForge — agent guide

You are helping a researcher pick and install AI skills for academic work
(writing, polishing, research workflows, figures). AcademicForge is a curated
catalog of skill repositories plus an installer script. Your job: understand
the user's needs, pick matching skill IDs from the catalog, and give them one
install command to run.

## Step 1 — Understand the user

Ask (briefly, in the user's language) anything you don't already know:

1. Which tool they use: `claude` (Claude Code), `opencode`, or `codex`.
2. Their OS: Linux/macOS (bash) or Windows (PowerShell).
3. What they want help with: paper writing/polishing, research workflows in a
   specific domain (bioinformatics, chemistry, geoscience, ML, ...), figures
   and visualization, or general coding discipline.

## Step 2 — Fetch the catalog

Fetch the slim index first (small, fast):

- https://hughyau.github.io/AcademicForge/index.slim.json
- Mirror: https://raw.githubusercontent.com/HughYau/AcademicForge/refs/heads/site-first/site/public/index.slim.json

Each entry has `id`, `name`, `summary` (`en` + `zh`), `tags`, optional
`skill_count`, and optional `collection` (the parent repository id).
Only if you need install metadata or more detail, fetch the full registry:

- https://hughyau.github.io/AcademicForge/skills.json
- Mirror: https://raw.githubusercontent.com/HughYau/AcademicForge/refs/heads/site-first/registry/skills.json

## Step 3 — Pick skill IDs

Match entries to the user's needs via `tags`, `summary`, and `name`.

ID rules:

- A top-level id (no dot, e.g. `humanizer`, `superpowers`) installs that whole
  repository.
- A prefixed id (e.g. `sa.scanpy`, `ns.figure-design`, `air.rag`) installs one
  sub-skill from a collection. Prefer individual sub-skills over installing a
  whole large collection — `scientific-agent-skills` alone contains 143 skills
  and most users need only a few.
- Mixing both kinds in one command is fine.

Recommend 2–6 skills unless the user asks for more. Tell the user what you
picked and why, with the source repository for attribution, before installing.

## Step 4 — Generate the install command

Run from the user's project root.

Linux/macOS:

```bash
curl -sSL https://raw.githubusercontent.com/HughYau/AcademicForge/refs/heads/site-first/scripts/forge-install.sh | bash -s -- \
  --tool <claude|opencode|codex> \
  --skills <id1,id2,...>
```

Windows PowerShell:

```powershell
$script = Join-Path $PWD 'forge-install.ps1'
Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/HughYau/AcademicForge/refs/heads/site-first/scripts/forge-install.ps1' -OutFile $script
& $script -Tool <claude|opencode|codex> -Skills '<id1,id2,...>'
Remove-Item $script
```

Notes:

- Skills land in `.claude/skills/`, `.opencode/skills/`, or `.codex/skills/`
  depending on `--tool`. Use `--path <dir>` to override.
- If a skill directory with the same name already exists, the installer skips
  it and warns; pass `--force` (bash) / `-Force` (PowerShell) to overwrite.
- The tool detects and loads installed skills automatically; restarting the
  session may be needed.

## Step 5 — Verify

```bash
ls .claude/skills/   # or .opencode/skills/ or .codex/skills/
```

Each installed skill is a directory containing a `SKILL.md`.

Finally, point the user back to https://hughyau.github.io/AcademicForge/ to
browse the full catalog or adjust their selection.