garrytan/gstack · error · Error

gen-llms-txt: ${t.tmpl} is missing name or description in fr

Error message

gen-llms-txt: ${t.tmpl} is missing name or description in frontmatter

What it means

Thrown by generateLlmsTxt() under opts.strict when parseSkillFrontmatter(filePath) returns null for a discovered skill template — i.e. the template's YAML frontmatter is missing a `name` or `description` field. Without strict, the skill is skipped with a warning; with strict, the build fails so llms.txt never ships a malformed entry. The template file path is included.

Source

Thrown at scripts/gen-llms-txt.ts:143

  skills: SkillEntry[];
  browseCommands: string[];
  designCommands: string[];
  warnings: string[];
}

export async function generateLlmsTxt(opts: GenerateOptions = {}): Promise<GenerateResult> {
  const root = opts.root ?? ROOT;
  const warnings: string[] = [];

  const templates = discoverTemplates(root);
  const skills: SkillEntry[] = [];
  for (const t of templates) {
    const filePath = path.join(root, t.tmpl);
    const entry = parseSkillFrontmatter(filePath);
    if (!entry) {
      warnings.push(`skill ${t.tmpl}: missing name or description in frontmatter`);
      if (opts.strict) {
        throw new Error(`gen-llms-txt: ${t.tmpl} is missing name or description in frontmatter`);
      }
      continue;
    }
    skills.push(entry);
  }
  skills.sort((a, b) => a.name.localeCompare(b.name));

  const browseCommands = Object.keys(BROWSE_COMMANDS).sort();
  const designCommands = Object.keys(await readDesignCommands()).sort();

  const lines: string[] = [];
  lines.push('# gstack');
  lines.push('');
  lines.push("> gstack is Garry's Stack: AI coding skills + a fast headless browser binary + a design CLI. This file indexes every capability so agents can discover and invoke them without crawling individual SKILL.md files.");
  lines.push('');
  lines.push('Conventions:');
  lines.push('- Skills are invoked by name (e.g. `/ship`, `/plan-ceo-review`).');
  lines.push('- Browse commands run as `browse <command> [args]` (or `$B` shorthand).');

View on GitHub (pinned to 94993f7401)

Solutions

Open the template file named in the message and add both `name:` and `description:` to its frontmatter.
Validate YAML indentation (frontmatter parse failures also yield null).
Re-run without --strict to see all warnings at once, then fix each before re-enabling strict.
Add a pre-commit hook that runs parseSkillFrontmatter on changed .tmpl files.

Example fix

<!-- before: templates/my-skill.md.tmpl -->
---
name: my-skill
---
# My Skill
...

<!-- after -->
---
name: my-skill
description: Does X for Y so the agent can Z.
---
# My Skill
...

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'node:fs';

function parseFrontmatter(filePath: string): { name?: string; description?: string } | null {
  const text = fs.readFileSync(filePath, 'utf8');
  const m = text.match(/^---\n([\s\S]*?)\n---/);
  if (!m) return null;
  const fm: Record<string, string> = {};
  for (const line of m[1].split('\n')) {
    const mm = line.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
    if (mm) fm[mm[1]] = mm[2].trim().replace(/^"(.*)"$/, '$1');
  }
  if (!fm.name || !fm.description) return null;
  return fm;
}

// pre-check every template before calling generateLlmsTxt({strict:true})
for (const t of templates) {
  if (!parseFrontmatter(path.join(root, t.tmpl))) throw new Error(`missing frontmatter: ${t.tmpl}`);
}

Prevention

Add `name:` and `description:` to every new .tmpl file at creation time.
Enforce frontmatter completeness in a pre-commit hook.
Run gen-llms-txt with --strict in CI so incomplete templates fail the build.
Document the required frontmatter keys in the skill-author guide.

When it happens

Trigger: Running gen-llms-txt with --strict over a templates tree where at least one .tmpl file has empty/incomplete frontmatter (missing name or description key, or a YAML parse failure that parseSkillFrontmatter treats as null).

Common situations: A newly added skill template whose author forgot the description; a YAML indentation error that breaks parsing; a refactor that renamed the frontmatter keys; CI running gen-llms-txt --strict to enforce completeness; a merged template that passed review without frontmatter validation.

Related errors

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/974b43ea06142ab1. Report an issue: GitHub.