lynx-website: Skill for Claude Code

Documentation Page Description Governance

This skill helps you audit and optimize frontmatter description fields across documentation pages. Well-governed descriptions keep generated outputs (like llms.txt) compact and meaningful, and also improve SEO and link previews.

Why This Matters

Pages without explicit description frontmatter fall back to their first paragraph — often hundreds of tokens of prose, unresolved MDX variables, JSX tags, or import statements. This bloats any consumer of the description (llms.txt, meta tags, link previews). The goal is to ensure every page has a deliberate, concise description that stays within a token budget (typically 30 tokens as measured by tiktoken gpt-4o).

Workflow

1. Audit Current State

Use the built llms.txt as a detection surface — it exposes every page's effective description in one file. Identify entries exceeding the token budget:

import { encodingForModel } from 'js-tiktoken';
import fs from 'node:fs/promises';

const enc = encodingForModel('gpt-4o');
const TOKEN_LIMIT = 30;

const llmsTxt = await fs.readFile('doc_build/llms.txt', 'utf-8');
const appendixStart = llmsTxt.indexOf('## 98. Appendix: Links');
const appendixContent = llmsTxt.slice(appendixStart);
const lines = appendixContent.split('\n').filter((l) => l.startsWith('* ['));

for (const line of lines) {
  const match = line.match(/^\* \[([^\]]*)\]\(([^)]+)\): (.+)$/);
  if (!match) continue;
  const [, title, url, desc] = match;
  const tokens = enc.encode(desc).length;
  if (tokens > TOKEN_LIMIT) {
    console.log(`${tokens} tokens: ${url} | ${desc.slice(0, 80)}`);
  }
}

Count tokens with tiktoken, not word count. Word-splitting (split(/\s+/)) severely undercounts Chinese/Japanese text where each character is 1-2 tokens.

2. Classify Each Overlong Entry

For each entry exceeding the budget, determine the fix strategy:

Situation	Fix
File has no frontmatter description	Add description field to frontmatter
File already has a frontmatter description that's too long	Do NOT modify the source — rely on postprocess truncation
Description contains unresolved MDX variables ({someVar['key']})	Add a proper description frontmatter to override
Description contains JSX/import leakage	Add a proper description frontmatter to override