/help-beacon

Sets up an AI-powered chat beacon that provides instant help by searching documentation and using Claude AI to answer questions. The beacon is a floating chat widget users can embed in any React application.

How It Works

Client-side search first -- searches article titles, tags, and content for instant matches before calling the API.
Claude AI -- sends relevant articles as context so the model gives grounded answers drawn from real documentation. Requires ANTHROPIC_API_KEY.
Human fallback -- when AI cannot answer, displays a "Contact Support" card that links to the supportEmail or supportUrl from help.config.json.

Setup Steps

Verify config exists. Check for help.config.json in the working directory. If it is missing, suggest running /help init first.
Read the config. Parse help.config.json and inspect any existing beacon section.
Choose position. Ask the user to choose where the floating button appears:
- bottom-right (default)
- bottom-left
Choose greeting message. Ask for a custom greeting (or accept the default "Hi! How can I help you?").

Update config. Write back to help.config.json with:

{
  "beacon": {
    "enabled": true,
    "provider": "claude",
    "greeting": "<chosen greeting>",
    "fallbackMessage": "I couldn't find an answer. Would you like to contact support?",
    "position": "<chosen position>"
  }
}

Detect framework. Use {{SKILL_DIR}}/utils/projectDetector.ts logic to determine the user's framework (nextjs-app, nextjs-pages, vite-react, astro, or unknown).

Scaffold beacon files into the user's project.

Copy these files from the skill into the user's source tree:

File	Destination
`{{SKILL_DIR}}/components/HelpBeacon.tsx`	`components/HelpBeacon.tsx` (or `src/components/`)
`{{SKILL_DIR}}/hooks/useBeacon.ts`	`hooks/useBeacon.ts` (or `src/hooks/`)

Then generate a server-side API route depending on the framework:

Framework	API route location
Next.js App Router	`app/api/help-chat/route.ts`
Next.js Pages Router	`pages/api/help-chat.ts`
Express + React Router	`routes/help-chat.ts` (mounted as `POST /api/help-chat`)
Vite	Express middleware or Vite plugin endpoint
Astro	`src/pages/api/help-chat.ts`
Unknown	Standalone `help-chat-server.ts` script

Add env variable. Append ANTHROPIC_API_KEY= to .env.example if it is not already present.

Show integration snippet. Print the code the user needs to add <HelpBeacon /> to their layout:

import { HelpBeacon } from './components/HelpBeacon';

// In your layout or root component:
<HelpBeacon
  config={{
    enabled: true,
    provider: 'claude',
    greeting: 'Hi! How can I help you?',
    fallbackMessage: "I couldn't find an answer. Would you like to contact support?",
    position: 'bottom-right',
    supportEmail: 'support@example.com',
  }}
  onSendMessage={async (messages) => {
    const res = await fetch('/api/help-chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ messages }),
    });
    const data = await res.json();
    return data.reply;
  }}
/>

Remind about the API key. Tell the user to set ANTHROPIC_API_KEY in their environment or .env file before the beacon will respond with AI answers.

API Route Template

The generated API route should follow this structure regardless of framework:

// Accept POST { messages: ChatMessage[] }
// 1. Read articles from the articles directory
// 2. Build a system prompt grounding the AI in documentation
// 3. Call the Anthropic API with relevant articles as context
// 4. Return { reply: string }
// 5. On error, return the fallback message from config

import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
import { join, resolve, basename } from 'path';

interface ChatMessage {
  role: 'user' | 'assistant';
  content: string;
}

// POST handler
export async function handleChat(messages: ChatMessage[]) {
  const configPath = resolve(process.cwd(), 'help.config.json');
  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
  const articlesDir = resolve(process.cwd(), config.settings.articlesDir);

  // Collect all markdown files recursively
  const articles = collectArticles(articlesDir);

  // Build context from articles
  const context = articles
    .map(a => `## ${a.title}\n${a.content}`)
    .join('\n\n---\n\n');

  const systemPrompt = `You are a helpful support assistant for "${config.project.name}". Answer using only the help articles below. Be concise. If you cannot find an answer, say so.\n\n--- HELP ARTICLES ---\n${context}`;

  const apiKey = process.env.ANTHROPIC_API_KEY;
  if (!apiKey) {
    return { reply: config.beacon.fallbackMessage };
  }

  const response = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
      'anthropic-version': '2023-06-01',
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      system: systemPrompt,
      messages,
    }),
  });

  if (!response.ok) {
    return { reply: config.beacon.fallbackMessage };
  }

  const result = await response.json();
  return { reply: result.content?.[0]?.text || config.beacon.fallbackMessage };
}

Configuration Reference

The beacon section of help.config.json:

{
  "beacon": {
    "enabled": true,
    "provider": "claude",
    "greeting": "Hi! How can I help you?",
    "fallbackMessage": "I couldn't find an answer. Would you like to contact support?",
    "position": "bottom-right"
  }
}

Field	Type	Description
`enabled`	`boolean`	Whether the beacon widget is active. Set to `false` to hide it.
`provider`	`string`	AI provider to use. Currently only `"claude"` is supported.
`greeting`	`string`	The initial message shown when the user opens the chat panel.
`fallbackMessage`	`string`	Message shown when the AI cannot answer or the API is unavailable.
`position`	`"bottom-right" \| "bottom-left"`	Corner where the floating button appears.

The project section provides support fallback info:

Field	Type	Description
`supportEmail`	`string`	Email address shown in the "Contact Support" fallback card.
`supportUrl`	`string`	URL linked from the "Contact Support" fallback card (optional).

Troubleshooting

Problem	Solution
Beacon not showing	Ensure `beacon.enabled` is `true` in `help.config.json` and the `<HelpBeacon />` component is rendered in your layout.
AI not responding	Verify that `ANTHROPIC_API_KEY` is set in your environment. Check your server logs for API errors.
Wrong position	Update `beacon.position` in `help.config.json` to `"bottom-right"` or `"bottom-left"`.
Answers not relevant	Ensure your `articles/` directory contains comprehensive, well-tagged content. The AI can only reference articles it is given as context.
"Contact Support" always showing	This appears when the AI indicates it cannot answer. Add more articles covering the topic, or check that your API key is valid.
Styling conflicts	The beacon uses inline styles to avoid CSS conflicts. If your app sets aggressive global styles (e.g., `* { box-sizing: ... }`), the beacon layout may shift. Wrap it in a container with `all: initial` if needed.