fix(llms.txt): link skills by generated path, drop host-skipped skills

gen-llms-txt built every skill link as <name>/SKILL.md, so the router
pointed at a nonexistent gstack/SKILL.md (it is the root SKILL.md) and
/claude-code pointed at a SKILL.md the Claude host never generates.
Links now use the template's generated output path, and skills the
Claude host skips are left out of the index. Adopts #2279.

Co-authored-by: Nader Helmy <creator.nader@gmail.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
committed 2026-10-08 06:16:55 +00:00
1 parent dfeae47a17
commit 6a46e8c22a
3 files changed
+19 -6

No files matched your search

+1 -2
View File
@@ -16,7 +16,6 @@ Conventions:
- [/browse](browse/SKILL.md): Drive a real browser through Aside: open a page, read it, click through a flow, take screenshots, check console errors.
- [/canary](canary/SKILL.md): Post-deploy canary monitoring.
- [/careful](careful/SKILL.md): Safety guardrails for destructive commands.
- [/claude-code](claude-code/SKILL.md): Claude Code CLI second opinion for non-Claude Code hosts.
- [/codex](codex/SKILL.md): OpenAI Codex CLI wrapper — three modes.
- [/context-restore](context-restore/SKILL.md): Restore working context saved earlier by /context-save.
- [/context-save](context-save/SKILL.md): Save working context.
@@ -31,7 +30,7 @@ Conventions:
- [/document-generate](document-generate/SKILL.md): Generate missing documentation from scratch for a feature, module, or entire project.
- [/document-release](document-release/SKILL.md): Release documentation audit.
- [/freeze](freeze/SKILL.md): Restrict file edits to a specific directory for the session.
- [/gstack](gstack/SKILL.md): Router for the gstack skill suite.
- [/gstack](SKILL.md): Router for the gstack skill suite.
- [/gstack-upgrade](gstack-upgrade/SKILL.md): Upgrade gstack to the latest version.
- [/guard](guard/SKILL.md): Full safety mode: destructive command warnings + directory-scoped edits.
- [/health](health/SKILL.md): Code quality dashboard.
+11 -4
View File
@@ -11,6 +11,10 @@
*
* Output: gstack/llms.txt at repo root.
*
* Skill links point at the Claude host's generated SKILL.md (the files this
* checkout ships). Skills the Claude host skips (claude-code) have no such
* file, so they are left out of the index rather than linked to a template.
*
* Refresh: invoked from scripts/gen-skill-docs.ts after SKILL.md generation
* so it regenerates automatically on every skill change.
*
@@ -20,7 +24,8 @@
import * as fs from 'fs';
import * as path from 'path';
import { mkdirpSync } from '../lib/fs-utils';
import { discoverTemplates } from './discover-skills';
import { discoverTemplates, includesSkill } from './discover-skills';
import claudeHost from '../hosts/claude';
import { COMMAND_DESCRIPTIONS as BROWSE_COMMANDS } from '../browse/src/commands';
const ROOT = path.resolve(import.meta.dir, '..');
@@ -29,6 +34,7 @@ const OUTPUT = path.join(ROOT, 'gstack', 'llms.txt');
interface SkillEntry {
name: string;
description: string;
output: string;
}
/**
@@ -36,7 +42,7 @@ interface SkillEntry {
* `name` and `description`. description: | followed by indented lines is
* the gstack convention; we collapse those into a single paragraph.
*/
function parseSkillFrontmatter(filePath: string): SkillEntry | null {
function parseSkillFrontmatter(filePath: string): Omit<SkillEntry, 'output'> | null {
const content = fs.readFileSync(filePath, 'utf-8');
if (!content.startsWith('---')) return null;
const end = content.indexOf('\n---', 3);
@@ -136,6 +142,7 @@ export async function generateLlmsTxt(opts: GenerateOptions = {}): Promise<Gener
const templates = discoverTemplates(root);
const skills: SkillEntry[] = [];
for (const t of templates) {
if (!includesSkill(claudeHost, path.dirname(t.tmpl))) continue;
const filePath = path.join(root, t.tmpl);
const entry = parseSkillFrontmatter(filePath);
if (!entry) {
@@ -145,7 +152,7 @@ export async function generateLlmsTxt(opts: GenerateOptions = {}): Promise<Gener
}
continue;
}
skills.push(entry);
skills.push({ ...entry, output: t.output });
}
skills.sort((a, b) => a.name.localeCompare(b.name));
@@ -168,7 +175,7 @@ export async function generateLlmsTxt(opts: GenerateOptions = {}): Promise<Gener
lines.push('');
for (const skill of skills) {
const summary = oneLine(skill.description);
lines.push(`- [/${skill.name}](${skill.name}/SKILL.md): ${summary}`);
lines.push(`- [/${skill.name}](${skill.output}): ${summary}`);
}
lines.push('');
+7
View File
@@ -36,6 +36,13 @@ describe('gen-llms-txt — shape', () => {
}
});
test('every link in the index resolves to an existing file', () => {
const links = [...generated.content.matchAll(/\]\(([^)]+)\)/g)].map((m) => m[1]);
expect(links.length).toBeGreaterThanOrEqual(generated.skills.length);
const missing = links.filter((href) => !fs.existsSync(path.join(ROOT, href)));
expect(missing).toEqual([]);
});
test('every browse command in COMMAND_DESCRIPTIONS appears in the index', () => {
expect(generated.browseCommands.length).toBeGreaterThan(0);
for (const cmd of generated.browseCommands) {