Consolidate 18 skills into 1 /impeccable skill with 20 commands

Biggest change in a while. Users previously had 18 standalone skill
entries cluttering their /menu; now they have one entry (/impeccable)
that routes to 20 specialized commands via argument dispatch. The pin
mechanism (/impeccable pin audit) restores standalone shortcuts on
demand for commands users hit all the time.

## Architecture

- Single /impeccable skill with command router section in SKILL.md
- 20 commands served via reference files under source/skills/impeccable/reference/
- /impeccable pin <command> creates a lightweight redirect shim so users
  who prefer /audit, /polish, etc. can still have them
- Context gathering (teach) auto-runs on first use
- command-metadata.json is the single source of truth for command
  descriptions, argument hints, and relationships

## Site rewrite

- Docs URL: /skills renamed to /docs (with /skills permanent redirects)
- Homepage hero frames Impeccable as "one skill with 20 commands"
- "Get Started" split into 50/50 install + how-to-use with editorial
  numbered steps, /impeccable shown as the home command with three modes
- New /docs overview: home command hero card + dense category rows
  matching the old cheatsheet density, with leads-to/pairs-with/
  combines-with relationship metadata served from a shared source
- Cheatsheet merged into /docs, /cheatsheet redirects
- Magazine spread and mobile cards show /impeccable as a stacked
  namespace label above the command name at full display size
- Periodic table updated with craft/teach/extract as first-class cells
- Skill detail pages generate from reference files, with an editorial
  wrapper per command for tagline + body
- Tutorials and anti-patterns pages updated to use /impeccable <cmd>

## Build system

- Dead code removed (scripts/lib/transformers/shared.js)
- Build log wording fixed ("1 skill" not "1 skills (1 user-invocable)")
- generateApiData fallback branch removed (throws loudly if metadata
  missing instead of silently degrading)
- Commands API includes editorial tagline alongside the long description;
  UI surfaces prefer tagline for human display, description for auto-
  trigger keyword matching

## Gitignore

- Added .claude/scheduled_tasks.lock, .claude/settings.local.json to
  ignore list (local Claude Code state that should not be tracked).
- Harness skill directories (.claude/skills/, .agents/skills/, etc.)
  remain tracked by design: npx skills reads them from this repo at
  install time and they enable clean submodule use.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

scripts/lib/render-markdown.js

@@ -82,7 +82,7 @@ export function createRenderer({ knownSkillIds = new Set(), currentSkillId = nul
  *
  * - `http(s)://…` → unchanged, external
  * - `reference/foo.md` → `#reference-foo` on current skill page
- * - `/skill-id` (known) → `/skills/skill-id`
+ * - `/skill-id` (known) → `/docs/skill-id`
  * - `#anchor` → unchanged (in-page anchor)
  * - anything else → unchanged (will be caught by build warnings later)
  *
@@ -112,12 +112,12 @@ function resolveHref(href, { knownSkillIds, currentSkillId }) {
   // /skill-id mentioned in prose (e.g. "run /polish")
   const slashMatch = href.match(/^\/([a-z0-9-]+)$/i);
   if (slashMatch && knownSkillIds.has(slashMatch[1])) {
-    return { href: `/skills/${slashMatch[1]}`, external: false };
+    return { href: `/docs/${slashMatch[1]}`, external: false };
   }
 
-  // [text](other-skill) → /skills/other-skill
+  // [text](other-skill) → /docs/other-skill
   if (/^[a-z0-9-]+$/i.test(href) && knownSkillIds.has(href)) {
-    return { href: `/skills/${href}`, external: false };
+    return { href: `/docs/${href}`, external: false };
   }
 
   // Unknown — pass through. Generator can warn separately.

scripts/lib/sub-pages-data.js

@@ -13,7 +13,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { readSourceFiles, parseFrontmatter } from './utils.js';
+import { readSourceFiles, parseFrontmatter, replacePlaceholders } from './utils.js';
 import {
   DETECTION_LAYERS,
   VISUAL_EXAMPLES,
@@ -37,7 +37,6 @@ const EXCLUDED_SKILLS = new Set([
   'arrange',           // renamed to layout
   'normalize',         // merged into /polish
   'onboard',           // merged into /harden
-  'extract',           // merged into /impeccable extract
 ]);
 
 /**
@@ -48,6 +47,7 @@ const EXCLUDED_SKILLS = new Set([
 const SKILL_CATEGORIES = {
   // CREATE - build something new
   impeccable: 'create',
+  craft: 'create',
   shape: 'create',
   // EVALUATE - review and assess
   critique: 'evaluate',
@@ -69,9 +69,12 @@ const SKILL_CATEGORIES = {
   polish: 'harden',
   optimize: 'harden',
   harden: 'harden',
+  // SYSTEM - setup and tooling
+  teach: 'system',
+  extract: 'system',
 };
 
-export const CATEGORY_ORDER = ['create', 'evaluate', 'refine', 'simplify', 'harden'];
+export const CATEGORY_ORDER = ['create', 'evaluate', 'refine', 'simplify', 'harden', 'system'];
 
 export const CATEGORY_LABELS = {
   create: 'Create',
@@ -91,6 +94,43 @@ export const CATEGORY_DESCRIPTIONS = {
   system: 'Setup and tooling. Design system work, extraction, organization.',
 };
 
+/**
+ * How commands relate to each other. Mirrors public/js/data.js so the server
+ * can render the docs overview without loading the client bundle.
+ *
+ * - leadsTo: commands that typically follow this one (used for evaluators)
+ * - pairs: the inverse counterpart (bolder <-> quieter)
+ * - combinesWith: commands that work well alongside this one
+ */
+export const COMMAND_RELATIONSHIPS = {
+  // Create
+  craft: { combinesWith: ['shape'] },
+  shape: { combinesWith: ['craft'] },
+  // Evaluate (these are the "diagnostics" that lead to fixes)
+  audit: { leadsTo: ['harden', 'optimize', 'adapt', 'clarify'] },
+  critique: { leadsTo: ['polish', 'distill', 'bolder', 'quieter', 'typeset', 'layout'] },
+  // Refine
+  typeset: { combinesWith: ['bolder', 'polish'] },
+  layout: { combinesWith: ['distill', 'adapt'] },
+  colorize: { combinesWith: ['bolder', 'delight'] },
+  animate: { combinesWith: ['delight'] },
+  delight: { combinesWith: ['bolder', 'animate'] },
+  bolder: { pairs: 'quieter' },
+  quieter: { pairs: 'bolder' },
+  overdrive: { combinesWith: ['animate', 'delight'] },
+  // Simplify
+  distill: { combinesWith: ['quieter', 'polish'] },
+  clarify: { combinesWith: ['polish', 'adapt'] },
+  adapt: { combinesWith: ['polish', 'clarify'] },
+  // Harden
+  polish: {},
+  optimize: {},
+  harden: { combinesWith: ['optimize'] },
+  // System
+  teach: {},
+  extract: {},
+};
+
 /**
  * Parse the ANTIPATTERNS array out of src/detect-antipatterns.mjs.
  * Mirrors the trick in scripts/build.js validateAntipatternRules() so we
@@ -168,28 +208,76 @@ export async function buildSubPageData(rootDir) {
   const contentDir = path.join(rootDir, 'content/site');
   const commandDemos = await loadCommandDemos(rootDir);
 
-  // Filter to user-invocable, non-deprecated skills.
-  const skills = rawSkills
-    .filter((s) => s.userInvocable && !EXCLUDED_SKILLS.has(s.name))
-    .map((s) => {
-      const category = SKILL_CATEGORIES[s.name];
-      const editorial = readEditorialWrapper(contentDir, 'skills', s.name);
-      const demo = commandDemos[s.name] || null;
-      return {
-        id: s.name,
-        name: s.name,
-        description: s.description,
-        argumentHint: s.argumentHint,
-        category,
-        body: s.body,
-        references: s.references,
-        editorial, // may be null
-        demo, // may be null (e.g. /shape has no demo)
-      };
-    })
-    .sort((a, b) => a.name.localeCompare(b.name));
+  // After the v3.0 consolidation there's only one source skill (impeccable).
+  // Its reference/ directory holds one file per command (audit.md, polish.md, ...).
+  // We synthesize a virtual skill entry for each sub-command so the sub-page
+  // generators can keep rendering per-command pages, index cards, etc.
+  const impeccableSkill = rawSkills.find((s) => s.name === 'impeccable');
+  const metadataPath = path.join(rootDir, 'source/skills/impeccable/scripts/command-metadata.json');
+  let commandMetadata = {};
+  if (fs.existsSync(metadataPath)) {
+    commandMetadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+  }
 
-  // Validate the category map covers every user-invocable skill.
+  // Reference files and skill bodies use {{command_prefix}} placeholders that
+  // are normally replaced by the provider transformer at build time. For web
+  // rendering, resolve them here using the claude-code provider as the canonical
+  // form ("/" prefix). The list of all command names includes the root skill
+  // plus all sub-commands from metadata so cross-references render correctly.
+  const allCommandNames = ['impeccable', ...Object.keys(commandMetadata)];
+  const resolvePlaceholders = (content) =>
+    replacePlaceholders(content, 'claude-code', [], allCommandNames);
+
+  const skills = [];
+
+  // 1. The root impeccable skill itself.
+  if (impeccableSkill && !EXCLUDED_SKILLS.has(impeccableSkill.name)) {
+    const editorial = readEditorialWrapper(contentDir, 'skills', 'impeccable');
+    const demo = commandDemos['impeccable'] || null;
+    skills.push({
+      id: 'impeccable',
+      name: 'impeccable',
+      description: impeccableSkill.description,
+      argumentHint: impeccableSkill.argumentHint,
+      category: SKILL_CATEGORIES['impeccable'],
+      body: resolvePlaceholders(impeccableSkill.body),
+      references: (impeccableSkill.references || []).map((r) => ({
+        ...r,
+        content: resolvePlaceholders(r.content),
+      })),
+      editorial,
+      demo,
+      isSubCommand: false,
+    });
+  }
+
+  // 2. One virtual entry per sub-command, body sourced from its reference file.
+  if (impeccableSkill) {
+    for (const [cmdId, meta] of Object.entries(commandMetadata)) {
+      if (EXCLUDED_SKILLS.has(cmdId)) continue;
+      const refFile = impeccableSkill.references?.find((r) => r.name === cmdId);
+      if (!refFile) continue; // no reference file = no page
+
+      const editorial = readEditorialWrapper(contentDir, 'skills', cmdId);
+      const demo = commandDemos[cmdId] || null;
+      skills.push({
+        id: cmdId,
+        name: cmdId,
+        description: meta.description,
+        argumentHint: meta.argumentHint,
+        category: SKILL_CATEGORIES[cmdId],
+        body: resolvePlaceholders(refFile.content),
+        references: [], // sub-commands don't have their own references
+        editorial,
+        demo,
+        isSubCommand: true,
+      });
+    }
+  }
+
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+
+  // Validate the category map covers every skill entry.
   const missing = skills.filter((s) => !s.category).map((s) => s.id);
   if (missing.length > 0) {
     throw new Error(

scripts/lib/transformers/factory.js

@@ -123,10 +123,10 @@ export function createTransformer(config) {
       }
     }
 
-    const userInvocableCount = skills.filter((s) => s.userInvocable).length;
+    const skillWord = skills.length === 1 ? 'skill' : 'skills';
     const refInfo = refCount > 0 ? ` (${refCount} reference files)` : '';
     const scriptInfo = scriptCount > 0 ? ` (${scriptCount} script files)` : '';
     const prefixInfo = prefix ? ` [${prefix}prefixed]` : '';
-    console.log(`✓ ${displayName}${prefixInfo}: ${skills.length} skills (${userInvocableCount} user-invocable)${refInfo}${scriptInfo}`);
+    console.log(`✓ ${displayName}${prefixInfo}: ${skills.length} ${skillWord}${refInfo}${scriptInfo}`);
   };
 }

scripts/lib/transformers/index.js

@@ -1,6 +1,9 @@
 import { createTransformer } from './factory.js';
 import { PROVIDERS } from './providers.js';
 
+// Named exports exist primarily as stable spy targets for the test suite
+// (build.test.js uses spyOn(transformers, 'transformCursor') etc.). build.js
+// itself uses createTransformer + PROVIDERS directly, not these.
 export const transformCursor = createTransformer(PROVIDERS.cursor);
 export const transformClaudeCode = createTransformer(PROVIDERS['claude-code']);
 export const transformGemini = createTransformer(PROVIDERS.gemini);

scripts/lib/transformers/shared.js

@@ -1,81 +0,0 @@
-import path from 'path';
-import { cleanDir, ensureDir, writeFile, generateYamlFrontmatter, replacePlaceholders, prefixSkillReferences } from '../utils.js';
-
-/**
- * Shared transformer logic for all providers.
- *
- * @param {Object} config - Provider-specific configuration
- * @param {string} config.provider - Provider key for placeholders (e.g., 'claude-code')
- * @param {string} config.displayName - Display name for logging (e.g., 'Claude Code')
- * @param {string} config.configDir - Dot-directory name (e.g., '.claude')
- * @param {Function} config.buildFrontmatter - (skill, skillName) => frontmatter object
- * @param {Function} [config.transformBody] - Optional (body, skill) => transformed body
- * @param {Array} skills - All skills
- * @param {string} distDir - Distribution output directory
- * @param {Object} options - Optional settings (prefix, outputSuffix)
- */
-export function transformProvider(config, skills, distDir, options = {}) {
-  const { provider, displayName, configDir, buildFrontmatter, transformBody } = config;
-  const { prefix = '', outputSuffix = '' } = options;
-  const providerDir = path.join(distDir, `${provider}${outputSuffix}`);
-  const skillsDir = path.join(providerDir, `${configDir}/skills`);
-
-  cleanDir(providerDir);
-  ensureDir(skillsDir);
-
-  const allSkillNames = skills.map(s => s.name);
-  const commandNames = skills.filter(s => s.userInvokable).map(s => `${prefix}${s.name}`);
-  let refCount = 0;
-  let scriptCount = 0;
-
-  for (const skill of skills) {
-    const skillName = `${prefix}${skill.name}`;
-    const skillDir = path.join(skillsDir, skillName);
-
-    const frontmatterObj = buildFrontmatter(skill, skillName);
-    const frontmatter = generateYamlFrontmatter(frontmatterObj);
-
-    let skillBody = replacePlaceholders(skill.body, provider, commandNames);
-
-    // Replace {{scripts_path}} with provider-aware path to skill's scripts directory
-    const scriptsPath = provider === 'claude-code'
-      ? '${CLAUDE_PLUGIN_ROOT}/scripts'
-      : `${configDir}/skills/${skillName}/scripts`;
-    skillBody = skillBody.replace(/\{\{scripts_path\}\}/g, scriptsPath);
-
-    if (prefix) skillBody = prefixSkillReferences(skillBody, prefix, allSkillNames);
-    if (transformBody) skillBody = transformBody(skillBody, skill);
-
-    const content = `${frontmatter}\n\n${skillBody}`;
-    writeFile(path.join(skillDir, 'SKILL.md'), content);
-
-    // Copy reference files if they exist
-    if (skill.references && skill.references.length > 0) {
-      const refDir = path.join(skillDir, 'reference');
-      ensureDir(refDir);
-      for (const ref of skill.references) {
-        writeFile(
-          path.join(refDir, `${ref.name}.md`),
-          replacePlaceholders(ref.content, provider)
-        );
-        refCount++;
-      }
-    }
-
-    // Copy script files if they exist
-    if (skill.scripts && skill.scripts.length > 0) {
-      const scriptsOutDir = path.join(skillDir, 'scripts');
-      ensureDir(scriptsOutDir);
-      for (const script of skill.scripts) {
-        writeFile(path.join(scriptsOutDir, script.name), script.content);
-        scriptCount++;
-      }
-    }
-  }
-
-  const userInvokableCount = skills.filter(s => s.userInvokable).length;
-  const refInfo = refCount > 0 ? ` (${refCount} reference files)` : '';
-  const scriptInfo = scriptCount > 0 ? ` (${scriptCount} script files)` : '';
-  const prefixInfo = prefix ? ` [${prefix}prefixed]` : '';
-  console.log(`✓ ${displayName}${prefixInfo}: ${skills.length} skills (${userInvokableCount} user-invokable)${refInfo}${scriptInfo}`);
-}

scripts/lib/utils.js

@@ -426,13 +426,33 @@ const EXCLUDED_FROM_SUGGESTIONS = new Set([
   'frontend-design', 'i-frontend-design',      // deprecated shim
 ]);
 
+// Sub-commands of /impeccable that should appear in {{available_commands}}.
+// These are the commands that audit/critique/etc. reference when suggesting next steps.
+const IMPECCABLE_SUB_COMMANDS = [
+  'adapt', 'animate', 'audit', 'bolder', 'clarify', 'colorize',
+  'critique', 'delight', 'distill', 'harden', 'layout', 'optimize',
+  'overdrive', 'polish', 'quieter', 'shape', 'typeset',
+];
+
 export function replacePlaceholders(content, provider, commandNames = [], allSkillNames = []) {
   const placeholders = PROVIDER_PLACEHOLDERS[provider] || PROVIDER_PLACEHOLDERS['cursor'];
   const cmdPrefix = placeholders.command_prefix || '/';
-  const commandList = commandNames
-    .filter(n => !EXCLUDED_FROM_SUGGESTIONS.has(n))
-    .map(n => `${cmdPrefix}${n}`)
-    .join(', ');
+
+  // Build the available_commands list.
+  // After the v3.0 consolidation, commands are sub-commands of /impeccable.
+  // If there's only one user-invocable skill (impeccable), generate sub-command references.
+  // Otherwise fall back to listing skill names (backwards compat for forks).
+  const nonExcluded = commandNames.filter(n => !EXCLUDED_FROM_SUGGESTIONS.has(n));
+  let commandList;
+  if (nonExcluded.length === 0) {
+    // Single-skill architecture: list sub-commands as /impeccable <sub>
+    commandList = IMPECCABLE_SUB_COMMANDS
+      .map(n => `${cmdPrefix}impeccable ${n}`)
+      .join(', ');
+  } else {
+    // Multi-skill architecture (backwards compat)
+    commandList = nonExcluded.map(n => `${cmdPrefix}${n}`).join(', ');
+  }
 
   let result = content
     .replace(/\{\{model\}\}/g, placeholders.model)