/help

Manage help documentation for any project. Initialize a help center structure, generate articles from your codebase, import from an existing help site, set up a dashboard, and preview it locally.

Capabilities

Routing Logic

1. Explicit intent (first match wins)

2. Project-state fallback

Init

Create help documentation infrastructure.

Steps

1. Check if help.config.json exists in the working directory. If it does, show the user the current config and ask before overwriting.
2. Ask the user for their project name.
3. Read the template config from {{SKILL_DIR}}/templates/help.config.json.
4. Replace {{PROJECT_NAME}} with the user’s chosen name.
5. Write the resulting config to help.config.json in the working directory.
6. Create an articles/ directory with category subdirectories (e.g., articles/getting-started/, articles/guides/, articles/faq/).
7. Copy template articles from {{SKILL_DIR}}/templates/articles/ into the matching subdirectories.
8. Confirm success and show the resulting directory structure.

Output

Created help.config.json
Created articles/
  getting-started/
    welcome.md
  guides/
  faq/

Run /help generate to create articles from your codebase.

Generate

AI-generate help articles by analyzing the codebase.

Steps

1. Verify help.config.json exists. If not, suggest running /help init first.
2. Read the config to get the project name, categories, and articlesDir.
3. Scan the codebase for documentation-worthy sources:
   • README files and existing docs
   • API routes and endpoint handlers
   • Component directories and their props/interfaces
   • Config files and environment variables
   • Error handling patterns and error codes
4. Present the discovered areas to the user. Ask which to document, or suggest a default set based on the scan.
5. For each chosen area, generate a markdown article with proper frontmatter:

   ---
   title: "Article Title"
   slug: "article-title"
   category: "getting-started"
   description: "Short description for search and SEO."
   visibility: public
   lastUpdated: "YYYY-MM-DD"
   ---
   

6. Write articles to the appropriate category directories under articlesDir.
7. If new categories were created, update help.config.json to include them.
8. Show a summary of all generated articles with their paths.

Update

Update existing articles or regenerate from code changes.

Steps

1. Read help.config.json and list all current articles with their lastUpdated dates.
2. Ask the user what to update:
   • A specific article (by title or path)
   • All articles in a category
   • Full regeneration of everything
3. Specific article:
   • Read the article’s current content.
   • Identify the relevant source code it documents.
   • Rewrite the content while preserving the frontmatter structure (slug, category, visibility).
   • Update the lastUpdated field.
4. Category or all:
   • Scan for source code changes since each article’s lastUpdated date.
   • Regenerate only the articles whose underlying code has changed.
   • Update lastUpdated on every modified article.
5. Show a diff summary: articles updated, articles unchanged, new articles suggested.

Import

Crawl a public help center URL and convert pages to markdown.

Steps

1. Ask the user for the help center base URL.
2. Attempt to find sitemap.xml at the URL (try /sitemap.xml and /help/sitemap.xml).
3. If no sitemap is found, crawl the main page and extract article links from navigation and content areas.
4. For each discovered page:
   • Fetch the HTML content.
   • Extract the article body (strip nav, footer, sidebar chrome).
   • Convert to clean markdown.
   • Generate frontmatter from page metadata:

     ---
     title: "Page Title"
     slug: "derived-from-url"
     category: "from-nav-structure"
     description: "From meta description tag"
     visibility: public
     lastUpdated: "YYYY-MM-DD"
     sourceUrl: "https://original-url"
     ---
     

5. Organize articles into categories based on the source site’s navigation structure.
6. Write all articles to the articles/ directory.
7. Update help.config.json with all discovered categories.
8. Show summary: number of articles imported, categories created, any pages that failed.

Notes

• Only public, unauthenticated pages can be imported.
• Rate-limit requests to avoid overloading the source server.
• If the source site blocks crawling, inform the user and suggest manual copy-paste.

Dashboard

Set up the help center dashboard.

Steps

1. Ask the user to choose:

   • Standalone app — runs as a separate Vite app on port 3333
   • Integrated into existing product — embeds help pages into the user’s framework

2. Standalone:

   • Explain that it runs as a separate Vite app on port 3333, reading articles from the working directory.
   • Check that {{SKILL_DIR}} has dependencies installed. If not, run npm install --prefix {{SKILL_DIR}}.
   • Launch with:

     HELP_PROJECT_DIR="$(pwd)" npm run dev --prefix {{SKILL_DIR}}
     

   • Tell the user the dashboard is available at http://localhost:3333.

3. Integrated:

   • Detect the user’s framework using {{SKILL_DIR}}/utils/projectDetector.ts logic (check package.json for framework dependencies and inspect the project structure).

   • Scaffold framework-specific routes and components:

     Framework	What to scaffold
     Next.js App Router	/app/help/layout.tsx, /app/help/page.tsx, /app/help/[slug]/page.tsx
     Next.js Pages Router	/pages/help/index.tsx, /pages/help/[slug].tsx
     Express + React Router	Express routes for API + static images; React Router routes for /help and /help/:slug
     React + Vite	Help route component with client-side routing
     Astro	/src/pages/help/index.astro, /src/pages/help/[slug].astro
     Unknown	Fall back to standalone app

   • Copy relevant components from {{SKILL_DIR}}/components/ into the user’s project (e.g., HelpProvider.tsx, HelpArticle.tsx, HelpSidebar.tsx).

   • Copy hooks from {{SKILL_DIR}}/hooks/ into the user’s project (e.g., useHelp.ts, useHelpSearch.ts).

   • Install required dependencies: react-markdown.

   • Images: Copy any images/ directory from the articles folder into the framework’s public static directory:

     Framework	Copy images to	Set imageBasePath to
     Next.js (App/Pages)	public/help/images/	/help/images
     Express + React Router	public/help/images/	/help/images
     React + Vite	public/help/images/	/help/images
     Astro	public/help/images/	/help/images

   • Pass imageBasePath to <HelpArticle> and <HelpSidebar> components so relative image paths in articles resolve correctly.

Express + React Router Details

When the detected framework is express-react, scaffold the following:

1. Express API routes — routes/help.ts (or src/routes/help.ts)

import { Router } from 'express';
import fs from 'fs';
import path from 'path';

const router = Router();

function readConfig() {
  return JSON.parse(fs.readFileSync(path.resolve('help.config.json'), 'utf-8'));
}

function collectMd(dir: string): string[] {
  if (!fs.existsSync(dir)) return [];
  const results: string[] = [];
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const full = path.join(dir, entry.name);
    if (entry.isDirectory()) results.push(...collectMd(full));
    else if (entry.name.endsWith('.md')) results.push(full);
  }
  return results;
}

function parseFrontmatter(raw: string) {
  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
  if (!m) return { data: {} as Record<string,string>, content: raw };
  const data: Record<string,string> = {};
  for (const line of m[1].split('\n')) {
    const i = line.indexOf(':');
    if (i > -1) data[line.slice(0,i).trim()] = line.slice(i+1).trim().replace(/^"|"$/g,'');
  }
  return { data, content: m[2] };
}

function getArticles() {
  const config = readConfig();
  const dir = path.resolve(config.settings.articlesDir);
  return collectMd(dir).map(f => {
    const { data, content } = parseFrontmatter(fs.readFileSync(f,'utf-8'));
    return { ...data, slug: data.slug || path.basename(f,'.md'), content };
  });
}

// GET /api/help/config
router.get('/config', (_req, res) => {
  res.json(readConfig());
});

// GET /api/help/articles
router.get('/articles', (_req, res) => {
  res.json(getArticles().map(({ content: _, ...rest }) => rest));
});

// GET /api/help/articles/:slug
router.get('/articles/:slug', (req, res) => {
  const article = getArticles().find(a => a.slug === req.params.slug);
  if (!article) return res.status(404).json({ error: 'Not found' });
  res.json(article);
});

// GET /api/help/search?q=term
router.get('/search', (req, res) => {
  const q = String(req.query.q || '').toLowerCase();
  if (!q) return res.json([]);
  const results = getArticles().filter(a =>
    [a.title,a.summary,a.content,...(a.tags||[])].join(' ').toLowerCase().includes(q)
  );
  res.json(results.map(({ content: _, ...rest }) => rest));
});

export default router;

Tell the user to mount this in their Express app:

import helpRoutes from './routes/help';
app.use('/api/help', helpRoutes);

Also add static image serving:

import express from 'express';
app.use('/help/images', express.static('public/help/images'));

2. React Router routes — pages/HelpPage.tsx (or src/pages/HelpPage.tsx)

import { Routes, Route } from 'react-router-dom';
import { HelpProvider } from '../components/HelpProvider';
import { HelpCenter } from '../components/HelpCenter';
import { HelpArticlePage } from '../components/HelpArticlePage';

export default function HelpPage() {
  return (
    <HelpProvider config={config} articles={articles}>
      <Routes>
        <Route index element={<HelpCenter />} />
        <Route path=":slug" element={<HelpArticlePage />} />
      </Routes>
    </HelpProvider>
  );
}

Also scaffold two page-level components that the routes render:

• HelpCenter.tsx — Lists all articles grouped by category with search. Uses useHelp() and useHelpSearch() from the scaffolded hooks. Uses useNavigate() from React Router to navigate to /help/:slug.
• HelpArticlePage.tsx — Reads slug from useParams(), fetches the article from /api/help/articles/:slug, and renders it with <HelpArticle imageBasePath="/help/images" />. Includes a back link to /help.

Tell the user to add the route to their router:

import HelpPage from './pages/HelpPage';

// In your <Routes>:
<Route path="/help/*" element={<HelpPage />} />

4. Confirm the setup and show usage instructions.

Preview

Launch the help dashboard for local preview.

Steps

1. Verify help.config.json exists in the working directory. If not, suggest running /help init.
2. Check if {{SKILL_DIR}} has node_modules/. If not, run:

   npm install --prefix {{SKILL_DIR}}
   

3. Start the Vite dev server:

   HELP_PROJECT_DIR="$(pwd)" npm run dev --prefix {{SKILL_DIR}}
   

4. Run the server in the background so the user can continue working.
5. Tell the user:
   • Dashboard is available at http://localhost:3333
   • Articles are live-reloaded on save
   • Press Ctrl+C or kill the background process to stop

Template Location

All templates live in {{SKILL_DIR}}/templates/:

templates/
  help.config.json          # Project config template
  articles/
    getting-started/
      welcome.md            # Default welcome article
    guides/
    faq/

Troubleshooting