Ref

Documentation search MCP server. This skill covers meta work (setup, config, decisions)—not mainline doc searching.

To search docs: Just call ref_search_documentation and ref_read_url directly. Don't invoke this skill.

How Ref Works

Search Philosophy

Ref uses agentic search: search() returns result overviews, then you selectively read() relevant pages. This matches how humans search—iterate and refine rather than batch retrieve.

What Gets Indexed

NOT indexed: Man pages, system docs, CLI --help output.

Freshness & Sync

• GitHub repos: Synced on 5-minute cron, incremental (compares commits)
• Uploaded files: Indexed immediately on upload
• Public index: Maintained by Ref team; request additions via form

Library Versions

Ref indexes the default branch (usually main). For specific versions:

• Check if the repo tags releases with docs
• Upload version-specific docs manually if needed
• Use ref_read_url on a specific commit/tag URL if available

Operations

Doctor

Health check and repair for Ref setup. Handles fresh installs AND fixes drift (missing auth, outdated config, missing best practices).

Run all checks in order. Fix issues as found.

Check 1: MCP Installation

claude mcp list

Install Flow:

1. Ask user with AskUserQuestion:

   • "I have a Ref account" → step 2
   • "I need to create one" → direct to https://ref.tools/signup, wait, then step 2

2. Tell user: "Go to https://ref.tools/install - paste the pre-populated command shown there."

3. Run the command user provides. Format:

   claude mcp add --transport http Ref https://api.ref.tools/mcp --header "x-ref-api-key: ref_..."
   

4. Restart required. Tell user:

   "Restart Claude Code (Cmd+R or relaunch), then say 'continue' to resume doctor."

5. After restart, re-run Check 1.

Check 2: Auth Validity

Test the API key works:

ref_search_documentation: "what is ref mcp server"

Check 3: Best Practices

Reference: https://docs.ref.tools/getting-started/best-practices

3a. Rules file exists

Check for project rules file that mentions Ref:

# Check common locations
cat CLAUDE.md 2>/dev/null | grep -i ref || echo "NOT_FOUND"
cat AGENTS.md 2>/dev/null | grep -i ref || echo "NOT_FOUND"
cat .claude/rules/*.md 2>/dev/null | grep -i ref || echo "NOT_FOUND"

If no rule found, ask:

• "Add Ref rule to CLAUDE.md" (Recommended)
• "Add Ref rule to AGENTS.md" (cross-tool compatible)
• "Skip for now"

If adding, append this line to chosen file:

When working with libraries, check the docs with Ref.

3b. Rule quality

The rule should be simple. Per best practices, avoid:

• Over-prompting (checking docs for every interaction)
• Excessive complexity

Good: When working with libraries, check the docs with Ref. Bad: Always check Ref before any code change and verify all imports...

If rule is overly complex, suggest simplifying.

Check 4: Verification

Final test - search Ref's own docs:

ref_search_documentation: "Claude Code MCP server installation"

Then read a result:

ref_read_url: <first relevant URL from results>

Report summary to user:

• MCP status
• Auth status
• Best practices status
• Test result

Dashboard Operations

No API yet—these are manual steps via web UI.

Adding a GitHub Repo

1. Go to ref.tools/resources?tab=github
2. Click Add GitHub Repos
3. Authenticate with GitHub if prompted (uses personal access token)
4. Select repos to index
5. Wait for initial sync (large repos may take a few minutes)

What gets indexed:

• Repos <2k files: everything (code + docs)
• Repos >2k files: docs only

Sync: Every 5 minutes, incremental. If you rewrite git history, remove and re-add the repo.

Uploading PDF/Markdown

1. Go to ref.tools/resources?tab=pdf
2. Click Add Files
3. Upload .pdf or .md files (max 100MB each)
4. Files are chunked and indexed automatically

Use case: Man pages, internal docs, version-specific library docs not in public index.

Viewing Usage

1. Go to ref.tools/activity
2. See daily credit spend by endpoint (search, read, chat, web)
3. Filter by date range
4. Export to CSV for audits

Managing API Keys

1. Go to ref.tools/keys
2. Create new keys, revoke old ones
3. Each key shows last used timestamp

Team Management

1. Go to ref.tools/team
2. Select team in workspace picker (top-left)
3. Invite members, assign roles

Roles:

Tip: For public-docs-only teams, have one Admin and invite everyone else as Readers.

Requesting Docs Be Added to Public Index

When Ref doesn't have docs for a library/tool you need:

Form details:

• Form ID: nrvBY2
• URL: https://tally.so/r/nrvBY2

Fields:

Request template:

<Tool/library name> - <what it is, 1 sentence>

<Why it's useful to index / what's currently missing, 1-2 sentences>

URL: <documentation URL>

Note: <any special notes about docs structure, size, format>

Common doc URLs:

• tmux: https://man.openbsd.org/tmux
• git: https://git-scm.com/docs

Submission: Use the Tally skill with:

formId: nrvBY2
fields:
  - name: "What docs would you like indexed?"
    value: <drafted request>
  - name: "Email"
    value: <user email>

After submitting: Ref team reviews and adds to public index. Check back in a few days.

Usage Reference

Search patterns:

• Include library name: "Effect Schema decode unknown data validation"
• Private docs: include ref_src=private in query

Decision Guide: Local Docs vs Ref Upload

When you have docs that aren't in Ref's public index (e.g., man pages):

Recommendation: