fix(skills): run bundled TTS helpers from the skill folder, not the working directory (#8035)

The media-use TTS and captions references ran heygen-tts.mjs and
heygen-voice.mjs as skills/media-use/... paths relative to the working
directory. Agents run these commands from the user's project, so a project
that ships a file at that path would run instead of the bundled helper.

Name the helpers through <SKILL_DIR>, as the rest of media-use does, and add
a skill lint rule that fails when a code block or inline command runs node,
python, bash, sh, tsx or bun on a relative script path. Docs whose commands
run inside a HyperFrames checkout, or only on a checked template kit, opt out
with a marker that states the reason.
This commit is contained in:
Michael Wang
2026-11-17 05:52:10 +00:00
committed by GitHub
parent 8a13b2cafa
commit 6115945cf4
10 changed files with 146 additions and 12 deletions
+65 -1
View File
@@ -11,7 +11,13 @@ import assert from "node:assert/strict";
import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { headingSlugs, lintDocRefs, lintFrontmatter, lintRegistryItemRefs } from "./lint-skills.ts";
import {
headingSlugs,
lintDocRefs,
lintFrontmatter,
lintRegistryItemRefs,
lintRelativeScriptRuns,
} from "./lint-skills.ts";
const wrap = (frontmatter) => `---\n${frontmatter}\n---\n\n# body\n`;
@@ -337,3 +343,61 @@ test("heading slugs: GitHub-style lowercasing, punctuation strip, dedupe", () =>
);
assert.deepEqual([...slugs], ["hello-world", "code--stuff", "hello-world-1"]);
});
// ---------------------------------------------------------------------------
// Helper scripts run by a working-directory-relative path
// ---------------------------------------------------------------------------
const fenced = (body) => "# Doc\n\n```bash\n" + body + "\n```\n";
test("relative scripts: a cwd-relative helper path in a code block is flagged", () => {
const violations = lintRelativeScriptRuns(
fenced("node skills/media-use/audio/scripts/heygen-tts.mjs a.txt -o a.wav"),
);
assert.equal(violations.length, 1);
assert.equal(violations[0].line, 4);
assert.match(violations[0].message, /skills\/media-use\/audio\/scripts\/heygen-tts\.mjs/);
});
test("relative scripts: other interpreters, bare names and ./ paths are flagged", () => {
for (const body of [
"python3 scripts/lint_source.py ./src",
"bash ./scripts/run.sh",
"npx tsx scripts/generate.ts",
"cd out && node locate.mjs overlay",
]) {
assert.equal(lintRelativeScriptRuns(fenced(body)).length, 1, body);
}
});
test("relative scripts: an inline code span in prose is checked too", () => {
const violations = lintRelativeScriptRuns("Run `python3 tools/voice.py --silent` first.\n");
assert.equal(violations.length, 1);
assert.equal(violations[0].line, 1);
});
test("relative scripts: skill-anchored, variable and absolute paths pass", () => {
for (const body of [
"node <SKILL_DIR>/audio/scripts/heygen-tts.mjs a.txt",
'node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" list',
'node "$SKILL_DIR/scripts/x.mjs"',
"node /opt/tools/x.mjs",
"node ~/tools/x.mjs",
"node -e 'console.log(1)'",
"npx hyperframes render",
]) {
assert.deepEqual(lintRelativeScriptRuns(fenced(body)), [], body);
}
});
test("relative scripts: a script named in prose without an interpreter is not flagged", () => {
assert.deepEqual(lintRelativeScriptRuns("`scripts/locate.mjs` narrows it with a grid.\n"), []);
});
test("relative scripts: a marker with a reason opts the doc out", () => {
const body = fenced("npx tsx scripts/generate.ts");
const marked = "<!-- skill-scripts: relative-ok, runs inside a HyperFrames checkout -->\n" + body;
assert.deepEqual(lintRelativeScriptRuns(marked), []);
const noReason = "<!-- skill-scripts: relative-ok -->\n" + body;
assert.equal(lintRelativeScriptRuns(noReason).length, 1);
});
+60
View File
@@ -509,6 +509,65 @@ export function lintDocRefs(filePath: string, content: string): LineViolation[]
.flatMap((ref) => checkDocRef(ref, filePath, content) ?? []);
}
// ---------------------------------------------------------------------------
// Helper scripts run by a working-directory-relative path
// ---------------------------------------------------------------------------
//
// An agent runs a skill's commands from the user's project directory, and that
// project may come from someone else. `node skills/x/scripts/y.mjs` or
// `node scripts/y.mjs` resolves inside that project, so a planted file with
// the same name runs instead of the bundled helper. A doc names its helpers
// through the skill's own folder (`<SKILL_DIR>/scripts/y.mjs`) instead.
//
// A doc whose relative commands are safe opts out with a marker line that
// says why, for example when its commands run inside a HyperFrames checkout
// rather than a user project:
//
// <!-- skill-scripts: relative-ok, runs inside a HyperFrames checkout -->
//
// Only interpreter invocations are seen: a script run directly (`./setup.sh`)
// or after interpreter flags (`node --test x.mjs`) is a known false negative.
const RELATIVE_SCRIPT_OPT_OUT = /<!--\s*skill-scripts:\s*relative-ok,\s*\S[^>]*-->/;
const CODE_FENCE = /^ {0,3}(?:```|~~~)/;
const RELATIVE_SCRIPT_RUN =
/(?:^|[\s(;&|])(?:node|python3?|bash|sh|tsx|bun)\s+["']?((?![<$/~"'-])[^\s"'`]+\.(?:mjs|cjs|js|ts|py|sh))(?=["'\s;)|&]|$)/;
/** Each fenced-block line and each inline code span, with its 1-based line number. */
function codeSegments(content: string): { text: string; line: number }[] {
const segments: { text: string; line: number }[] = [];
let inFence = false;
content.split("\n").forEach((text, index) => {
if (CODE_FENCE.test(text)) {
inFence = !inFence;
return;
}
if (inFence) {
segments.push({ text, line: index + 1 });
return;
}
for (const span of text.matchAll(INLINE_CODE_SPAN)) {
segments.push({ text: span[1] ?? "", line: index + 1 });
}
});
return segments;
}
export function lintRelativeScriptRuns(content: string): LineViolation[] {
if (RELATIVE_SCRIPT_OPT_OUT.test(content)) return [];
return codeSegments(content).flatMap(({ text, line }) => {
const script = RELATIVE_SCRIPT_RUN.exec(text)?.[1];
if (!script) return [];
return [
violation(
line,
`Runs \`${script}\` by a path relative to the working directory, which resolves inside the user's project. Name the bundled helper through its skill folder, for example \`<SKILL_DIR>/scripts/...\`.`,
text,
),
];
});
}
function collectMarkdownFiles(dir: string): string[] {
return readdirSync(dir, { withFileTypes: true, recursive: true })
.filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
@@ -537,6 +596,7 @@ function lintMarkdownFiles(paths: string[], knownItems: Set<string>, report: Rep
const content = readFileSync(path, "utf-8");
const file = relative(process.cwd(), path);
report(file, lintDocRefs(path, content));
report(file, lintRelativeScriptRuns(content));
const found = lintRegistryItemRefs(content, knownItems);
if (found === null) continue;
snapshotsChecked++;