setup

name	setup
description	This skill should be used when the user asks to "set up headkey", "configure headkey", "connect to headkey", mentions "HEADKEY_API_KEY", "HEADKEY_AGENT_ID", or discusses headkey configuration, authentication setup, or per-project agent configuration.
version	1.1.0

Headkey Setup Skill

This skill helps users configure their connection to the Headkey Memory API.

When This Skill Applies

• User wants to set up or configure the Headkey plugin
• User needs help with API key or agent ID configuration
• User is troubleshooting connection issues
• User wants to configure a different Headkey agent per project

Key Concepts

There are two types of API keys:

• Account key (recommended) — a single key for the user's Headkey account. Requires setting a per-project agent ID via HEADKEY_AGENT_ID (UUID or friendly slug).
• Agent key — a key tied to a specific agent. No agent ID header needed.

Account keys are preferred because you manage one key globally and just set the agent ID per project.

Configuration

Account Key (Recommended)

Set the API key globally in ~/.claude/settings.json:

{
  "env": {
    "HEADKEY_API_KEY": "cibfe_your_account_key_here"