secondbrain-search-init

name	secondbrain-search-init
description	This skill should be used when the user asks to "initialize search", "set up semantic search", "enable qmd", "add search to secondbrain", or mentions wanting to enable semantic search capabilities for an existing secondbrain project.

Initialize Semantic Search

Set up qmd semantic search for an existing secondbrain project.

Prerequisites

1. Secondbrain project exists: Check for .claude/data/config.yaml
2. qmd installed: Check with which qmd

Workflow

Step 1: Validate Environment

# Check secondbrain exists
ls .claude/data/config.yaml

# Check qmd installation
which qmd

If secondbrain not found:

No secondbrain project found in current directory.
Run `/secondbrain-init` to create a new project first.

If qmd not installed:

## qmd Not Installed

qmd is required for semantic search. Install it:

### Using Bun (Recommended)
bun install -g qmd

### Using npm
npm install -g qmd

After installation, run this skill again.

**Note:** First run will download ~1.5GB of embedding models.

Step 2: Check Existing Search

ls .claude/search/ 2>/dev/null

If search already initialized:

## Search Already Initialized

Search is already configured for this project.

**Index location:** .claude/search/
**Last indexed:** 2026-01-15 10:30

### Options

1. **Rebuild index** — Re-index all documents
   `/secondbrain-search-init --rebuild`

2. **Search now** — Start searching
   `/secondbrain-search "your query"`

3. **Check status** — View index statistics
   `qmd status`

Step 3: Create Search Configuration

Create .claude/search/ directory and qmd config:

mkdir -p .claude/search

Generate qmd.config.json in project root:

{
  "name": "{{project_name}}-secondbrain",
  "paths": ["docs"],
  "ignore": [
    "**/node_modules/**",
    "**/.vitepress/cache/**",
    "**/.vitepress/dist/**",
    "**/TEMPLATE.md"
  ],
  "indexDir": ".claude/search",
  "chunk": {
    "size": 800,
    "overlap": 0.15
  },
  "metadata": {
    "extractFrontmatter": true,
    "includeFileMetadata": true
  }
}

Step 4: Update .gitignore

Add search index to .gitignore (index should not be committed):

# Semantic search index (regenerate with /secondbrain-search-init)
.claude/search/
qmd.config.json

Step 5: Build Initial Index

Run initial indexing:

qmd index

Show progress:

## Building Search Index

Scanning docs/...
Found 47 documents

Indexing:
[████████████████████░░░░░░░░░░] 35/47 documents

Downloading models (first run only):
- embedding-gemma-300M... done
- qwen3-reranker... done

Building embeddings:
[██████████████████████████████] 47/47 documents

Index built successfully!
- Documents: 47
- Chunks: 312
- Index size: 2.4 MB
- Location: .claude/search/

Step 6: Register Hook (Optional)

Ask user if they want automatic index updates:

## Automatic Index Updates

Would you like to automatically update the search index
when documents are modified?

[x] Yes, add PostToolUse hook (Recommended)
    - Updates index incrementally on file changes
    - Adds ~0.5s to Write/Edit operations

[ ] No, I'll rebuild manually
    - Run `qmd index` or `/secondbrain-search-init --rebuild`

If yes, add hook to .claude/settings.local.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/search-index-update.py\"",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

Copy hook script:

cp "${CLAUDE_PLUGIN_ROOT}/hooks/search-index-update.py" .claude/hooks/

Step 7: Show Summary

## Search Initialized Successfully!

**Project:** my-knowledge-base
**Documents indexed:** 47
**Index location:** .claude/search/

### Quick Start

Search your knowledge base:
/secondbrain-search "kubernetes deployment strategies"

Search with filters:
/secondbrain-search --entity=adrs "database"
/secondbrain-search --recent=30d "authentication"

### Index Management

Rebuild index:
qmd index --rebuild

Check status:
qmd status

View recent searches:
qmd history

### Automatic Updates

Index updates: Enabled (PostToolUse hook)
Documents in docs/ will be re-indexed on save.

Options

--rebuild

Force rebuild of entire index:

qmd index --rebuild

--no-hook

Skip adding the automatic update hook:

/secondbrain-search-init --no-hook

Troubleshooting

Models Download Stuck

If model download hangs:

# Clear cache and retry
rm -rf ~/.cache/qmd/models/
qmd index

Index Corruption

If search returns errors:

# Remove and rebuild
rm -rf .claude/search/
qmd index

Slow Indexing

For large document sets (>500 docs):

• Initial indexing may take several minutes
• Consider using --batch-size=50 for progress visibility

Related Skills

• secondbrain-search — Search your knowledge base
• secondbrain-init — Create new secondbrain project