home / skills / dhughes / claude-marketplace / getting-started

getting-started skill

safe

/plugins/conversation-history/skills/getting-started

This skill guides you through initial setup and indexing of conversation history to ensure past conversations become searchable.

npx playbooks add skill dhughes/claude-marketplace --skill getting-started

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

1.7 KB

---
name: conversation-history-setup
description: Guide users through initial setup of conversation history indexing. Use when user asks about setting up conversation history, indexing past conversations, or when search returns no results and the database may be empty.
user-invocable: false
---

# Conversation History Setup

This skill helps users get started with the conversation-history plugin.

## When to Use

Invoke this guidance when:
- User asks how to set up conversation history
- User asks about indexing past/historical conversations
- Search returns no results and user seems surprised
- User mentions they just installed the plugin

## Initial Setup

After installing the conversation-history plugin, users should index their existing conversations:

```bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/getting-started/scripts/index-history.sh
```

Or they can run the command: `/conversation-history:index-history`

This scans `~/.claude/projects/` and indexes all existing conversation files into the database at `~/.claude/conversation-history.db`.

## How It Works

1. **Automatic indexing**: After setup, new conversations are automatically indexed via a Stop hook that fires when Claude finishes responding.

2. **Database location**: `~/.claude/conversation-history.db` - persists even after JSONL files are cleaned up.

3. **Incremental**: The indexer tracks what's already indexed and only processes new content.

## If Search Returns Nothing

If a user searches and gets no results:
1. Check if they've run the initial indexing
2. Suggest running `/conversation-history:index-history` to populate the database
3. Note that only conversations since the plugin was installed (or since running index-history) will be searchable

Overview

This skill guides users through the initial setup and indexing of conversation history for the conversation-history plugin. It explains how to populate the local database so past conversations become searchable. Use it to diagnose empty search results and to index historical conversation files.

How this skill works

Run a one-time index command to scan existing conversation files and populate a local SQLite database at ~/.claude/conversation-history.db. After indexing, new conversations are automatically captured by a Stop hook that adds content incrementally. The indexer is incremental and skips content already processed so repeated runs are safe.

When to use it

When a user asks how to enable or configure conversation history indexing.
When a user wants to index past or historical conversations into the searchable database.
When search returns no results and the database may be empty or not yet populated.
When the plugin was just installed and existing conversations aren’t appearing in searches.

Best practices

Run the initial indexing command after installation to populate the database: /conversation-history:index-history or use the provided script.
Confirm the database file exists at ~/.claude/conversation-history.db to ensure persistence beyond raw JSONL files.
Re-run indexing if you move or restore conversation files; the indexer is incremental and safe to run multiple times.
Check file permissions if the index command fails—ensure the plugin can read ~/.claude/projects/ and write to ~/.claude/.

Example use cases

A user installs the plugin and wants all past chats searchable—run the index script to import historical files.
A user searches and finds no matches—recommend running /conversation-history:index-history to populate the DB.
Migrating conversations from a backup—restore JSONL files and re-run indexing to update the database.
Confirming persistence—verify ~/.claude/conversation-history.db remains after cleaning up raw JSONL files.

FAQ

What command populates the conversation database?

Run /conversation-history:index-history or the included index-history.sh script to scan ~/.claude/projects/ and create ~/.claude/conversation-history.db.

Will new conversations be indexed automatically?

Yes. After setup, a Stop hook automatically indexes new conversations incrementally as Claude finishes responses.