Client Usage Modes

AI Research Skills can be used in several ways depending on your needs. Choose the approach that fits your workflow.

Mode A: Skills Only (No Code)

Best for: Researchers, students, practitioners who want to learn concrete research workflows.

Option 1: Browse the Docs Site

Visit the Skills page to search, filter, and read skills with nice formatting.

Search options:

Native docs search (top search box, powered by Pagefind)
Skills page keyword filter (always available)
Semantic search (optional / backup)

Semantic search is disabled by default (to keep deployments and costs simple). To enable it, set:

NEXT_PUBLIC_AIRS_ENABLE_SEMANTIC=1

When enabled, semantic search can use:

Cloudflare Pages Function: /api/semantic-search (recommended for consistent results)
Browser fallback: runs locally in your browser (downloads a small model on first use)

To reduce spam (and protect the daily free quota), the Cloudflare semantic endpoint can require Turnstile. When enabled, the Skills page will show a small human verification widget before semantic search requests are accepted.

Option 2: Read Raw Files

Open skills/<category>/<skill-name>/SKILL.md directly in any text editor or on GitHub.

skills/
├── research/
│   └── reference-formatting/SKILL.md
└── analysis/
    └── textual-analysis-basic/SKILL.md

Option 3: Copy/Paste into AI

Copy the skill content and paste it into your AI assistant (Claude, ChatGPT, etc.) for guidance while working.

Mode B: Validator (Contributors & CI)

Best for: Contributors adding new skills, maintainers running CI checks.

Local Validation

# Clone the repo
git clone https://github.com/boan-anbo/ai-research-skills.git
cd ai-research-skills

# Validate your changes
npm install
npm run validate:strict

Mode C: MCP Server (AI Integration)

Best for: Power users who want AI assistants to have structured access to skills and research tools.

What You Get

Programmatic skill discovery (skills.list, skills.get)
Semantic search across skills
Tool capabilities (PDF extraction, text analysis)

Setup

Install dependencies:

npm install

Configure your MCP client:

Claude Code / Claude Desktop:

{
  "mcpServers": {
    "airs": {
      "command": "/path/to/ai-research-skills/node_modules/.bin/tsx",
      "args": ["/path/to/ai-research-skills/mcp/airs-mcp.ts", "--skills-dir", "/path/to/ai-research-skills/skills"]
    }
  }
}

Generic MCP Client:

{
  "name": "airs",
  "command": "tsx",
  "args": ["mcp/airs-mcp.ts", "--skills-dir", "./skills"],
  "transport": "stdio"
}

Your AI assistant can now call AI Research Skills tools directly.

Comparison Table

Mode	Setup	Use Case	Requires
A: Skills Only	None	Reading/learning	Browser or text editor
B: Validator	Node.js	Contributing	`npm run validate:strict`
C: MCP Server	Node.js + MCP client	AI integration	MCP-compatible client

Which Should I Use?

┌─────────────────────────────────────────┐
│ Do you just want to read skills?        │
│                                         │
│   YES → Mode A (Skills Only)            │
│   NO  ↓                                 │
├─────────────────────────────────────────┤
│ Are you contributing new skills?        │
│                                         │
│   YES → Mode B (Validator)              │
│   NO  ↓                                 │
├─────────────────────────────────────────┤
│ Do you want AI to call DH tools?        │
│                                         │
│   YES → Mode C (MCP Server)             │
│   NO  → Mode A is enough                │
└─────────────────────────────────────────┘

CLI Tool - Validator installation and usage
MCP Server - Server configuration details
Contribute - How to add new skills