feat(skills): add changelog-video skill for repo-native CC + Codex discovery (#2552)

Packages Jake Moran's changelog-video pipeline (v1, validated end-to-end
by Home on the Jun 23-29 range) as a repo-native skill set that Claude
Code (.claude/skills/) and Codex CLI (.agents/skills/) auto-discover the
moment the repo is opened. No install step; run the skill against a
changelog markdown for a given git range and it produces a lint-clean,
seam-gate-green 1080x1080 MP4 (~45-60s, Annie VO, mock-UI visualizations,
caption rail) end-to-end.

Six skills added byte-identical in both mirror dirs:
- changelog-video (pipeline entry point)
- motion-doctrine (carries seam-stamp.mjs + seam-gate.mjs)
- cut-the-curve, captions-overlay, seam-craft, oversized-cursor

Layout:
- .claude/skills/  - Claude Code project-local auto-discover
- .agents/skills/  - Codex CLI project-local auto-discover (verified via
                     Magi's clean-home Codex 0.144.3 repro; NOT .codex/skills/)

Fonts, animated background (12 MB), house BGM (5 MB), lexicon, and
align-captions ship inside the skill dirs. .gitattributes routes only
.claude/skills/**/*.{mp4,mp3} + .agents/skills/**/*.{mp4,mp3} through
LFS — narrowly scoped so unrelated Player, Studio, registry, and
marketplace media stay put. HeyGen CLI auth is the one credential the
skill needs; Node >= 22, ffmpeg, and headless Chrome are documented
alongside in both READMEs.

.gitignore: rewrites .claude/ and .agents/ blocks to keep agent-installed
skill hygiene while re-including the six repo-native skill dirs plus
README.md.

CI:
- Extends changes.skills filter to match .claude/skills/**,
  .agents/skills/**, scripts/lint-skills.ts, and scripts/check-skill-mirror.mjs.
- New 'Skills: project-native lint + mirror' job runs the extended
  lint-skills.ts (schema-driven; required { name, description } + optional
  { license, allowed-tools, metadata }, name pattern check, description
  length check) plus a new check-skill-mirror.mjs byte-integrity script
  (24 mirrored files must match; README.md deliberately per-CLI).
- Wired into 'bun run lint' locally.

Frontmatter validator:
- Rejects unsupported top-level keys (catches category:-style drift).
- Requires name + description.
- Validates name pattern (^[a-z][a-z0-9-]{0,63}$) and description shape
  (non-empty, <=1024 chars).
- Missing frontmatter block itself is a first-class error.

Also strips unsupported top-level 'category:' frontmatter from Jake's
motion-doctrine and cut-the-curve SKILL.mds (both mirrors), rewrites the
TTS invocation from ~/.claude/skills/media-use/... to the tracked
skills/hyperframes-media/scripts/heygen-tts.mjs, swaps npx hyperframes@latest
for the repo-local CLI in the gate step, and fixes a lint issue in Jake's
seam-gate.mjs (ternary-for-side-effect -> if/else).

Validated end-to-end by Home on Jun 23-29 (MP4 posted in C0ACCNHLG3U
thread 1784181166.041319). Independently reviewed R1/R2/R3 by Magi.

Co-authored-by: Jake Moran <jake@heygen.com>
This commit is contained in:
James Russo
2026-07-16 17:29:19 -04:00
committed by GitHub
co-authored by Jake Moran
parent 172f2757f0
commit e96ebd74de
59 changed files with 5826 additions and 77 deletions
+80
View File
@@ -0,0 +1,80 @@
#!/usr/bin/env node
// Verifies .claude/skills/ and .agents/skills/ are byte-identical mirrors.
//
// The two dirs deliver the same skill set to Claude Code and Codex CLI
// respectively (each CLI reads only its own path). They must stay in lockstep
// or one CLI will silently ship a stale skill. This check enforces that
// invariant at CI time.
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join, relative } from "node:path";
import { createHash } from "node:crypto";
const REPO_ROOT = join(import.meta.dirname, "..");
const A = join(REPO_ROOT, ".claude", "skills");
const B = join(REPO_ROOT, ".agents", "skills");
// The two top-level READMEs deliberately differ (one addresses CC users, one
// addresses Codex CLI users). Skill CONTENT must mirror; per-CLI docs need not.
const MIRROR_EXCLUDE = new Set(["README.md"]);
function collectFile(dir, entry, base) {
if (!entry.isFile()) return [];
const rel = relative(base, join(dir, entry.name));
if (MIRROR_EXCLUDE.has(rel)) return [];
return [rel];
}
function walk(dir, base) {
if (!statSync(dir, { throwIfNoEntry: false })?.isDirectory()) return [];
const entries = readdirSync(dir, { withFileTypes: true });
const out = entries.flatMap((entry) =>
entry.isDirectory() ? walk(join(dir, entry.name), base) : collectFile(dir, entry, base),
);
return out.sort();
}
function hashFile(path) {
return createHash("sha256").update(readFileSync(path)).digest("hex");
}
const aFiles = walk(A, A);
const bFiles = walk(B, B);
const problems = [];
const aSet = new Set(aFiles);
const bSet = new Set(bFiles);
for (const rel of aFiles) {
if (!bSet.has(rel)) {
problems.push(`only in .claude/skills/: ${rel}`);
}
}
for (const rel of bFiles) {
if (!aSet.has(rel)) {
problems.push(`only in .agents/skills/: ${rel}`);
}
}
for (const rel of aFiles) {
if (!bSet.has(rel)) continue;
const aHash = hashFile(join(A, rel));
const bHash = hashFile(join(B, rel));
if (aHash !== bHash) {
problems.push(
`content differs: ${rel} (.claude=${aHash.slice(0, 8)} .agents=${bHash.slice(0, 8)})`,
);
}
}
if (problems.length > 0) {
console.error("Skill mirror out of sync between .claude/skills/ and .agents/skills/:\n");
for (const p of problems) console.error(` ${p}`);
console.error("\nRebuild the mirror: cp -r .claude/skills/. .agents/skills/ (or vice-versa)");
process.exit(1);
}
console.log(
`Skill mirror OK: ${aFiles.length} file(s) match byte-for-byte across .claude/skills/ and .agents/skills/.`,
);
+127
View File
@@ -0,0 +1,127 @@
// Positive / negative fixture tests for the SKILL.md frontmatter drift guard
// in scripts/lint-skills.ts. Runs the exported `lintFrontmatter` against known
// inputs and asserts the violation set matches expectation.
//
// Kept in .mjs (not .ts) so `node --test` can execute it via the same runner
// the rest of scripts/*.test.mjs use, without needing tsx. `bun scripts/…`
// runs .ts directly at lint-time; tests import the compiled export via tsx.
import test from "node:test";
import assert from "node:assert/strict";
import { lintFrontmatter } from "./lint-skills.ts";
const wrap = (frontmatter) => `---\n${frontmatter}\n---\n\n# body\n`;
// ---------------------------------------------------------------------------
// Positive fixtures — must pass with zero violations
// ---------------------------------------------------------------------------
test("valid: bare required keys", () => {
const violations = lintFrontmatter(wrap("name: foo\ndescription: bar"));
assert.deepEqual(violations, []);
});
test("valid: with license (optional string)", () => {
const violations = lintFrontmatter(wrap("name: foo\ndescription: bar\nlicense: MIT"));
assert.deepEqual(violations, []);
});
test("valid: allowed-tools as YAML sequence", () => {
const violations = lintFrontmatter(
wrap("name: foo\ndescription: bar\nallowed-tools:\n - Bash\n - Read"),
);
assert.deepEqual(violations, []);
});
test("valid: allowed-tools as single string", () => {
const violations = lintFrontmatter(wrap('name: foo\ndescription: bar\nallowed-tools: "Bash"'));
assert.deepEqual(violations, []);
});
test("valid: metadata as nested mapping", () => {
const violations = lintFrontmatter(
wrap("name: foo\ndescription: bar\nmetadata:\n version: 1\n tags:\n - a\n - b"),
);
assert.deepEqual(violations, []);
});
test("valid: multi-line description via block scalar", () => {
const violations = lintFrontmatter(
wrap("name: foo\ndescription: |\n Multi\n line\n description"),
);
assert.deepEqual(violations, []);
});
test("valid: description with a colon inside a quoted string", () => {
const violations = lintFrontmatter(wrap('name: foo\ndescription: "read: file, then: write"'));
assert.deepEqual(violations, []);
});
// ---------------------------------------------------------------------------
// Negative fixtures — must produce at least one matching violation
// ---------------------------------------------------------------------------
const has = (violations, needle) =>
violations.some((v) => v.message.toLowerCase().includes(needle.toLowerCase()));
test("invalid: missing frontmatter block", () => {
const violations = lintFrontmatter("# just a body, no dashes\n");
assert.ok(has(violations, "Missing SKILL.md YAML frontmatter"));
});
test("invalid: missing name", () => {
const violations = lintFrontmatter(wrap("description: bar"));
assert.ok(has(violations, `Missing required frontmatter key "name"`));
});
test("invalid: missing description", () => {
const violations = lintFrontmatter(wrap("name: foo"));
assert.ok(has(violations, `Missing required frontmatter key "description"`));
});
test("invalid: unsupported key (the 'category' drift case)", () => {
const violations = lintFrontmatter(wrap("name: foo\ndescription: bar\ncategory: motion"));
assert.ok(has(violations, `Unsupported frontmatter key "category"`));
});
test("invalid: name as a list (was silently accepted by the pre-YAML version)", () => {
const violations = lintFrontmatter(wrap("name: [a, b]\ndescription: bar"));
assert.ok(has(violations, `"name" must be a string`));
});
test("invalid: description as a number", () => {
const violations = lintFrontmatter(wrap("name: foo\ndescription: 42"));
assert.ok(has(violations, `"description" must be a string`));
});
test("invalid: empty description string", () => {
const violations = lintFrontmatter(wrap('name: foo\ndescription: ""'));
assert.ok(has(violations, `"description" must not be empty`));
});
test("invalid: allowed-tools as a mapping (must be sequence or string)", () => {
const violations = lintFrontmatter(
wrap("name: foo\ndescription: bar\nallowed-tools:\n Bash: true"),
);
assert.ok(has(violations, `"allowed-tools" must be a string or a list of strings`));
});
test("invalid: metadata as a scalar (must be a mapping)", () => {
const violations = lintFrontmatter(
wrap('name: foo\ndescription: bar\nmetadata: "just a string"'),
);
assert.ok(has(violations, `"metadata" must be a mapping`));
});
test("invalid: malformed YAML (unmatched brace)", () => {
const violations = lintFrontmatter(wrap("name: foo\ndescription: {"));
assert.ok(has(violations, `Malformed YAML frontmatter`));
});
test("invalid: top-level scalar (frontmatter is not a mapping)", () => {
const violations = lintFrontmatter("---\njust-a-string\n---\n\nbody");
// Either parse succeeds and the top-level check catches it, or the parser
// errors — either is an acceptable rejection, but the violation list must
// be non-empty.
assert.ok(violations.length > 0);
});
+186 -55
View File
@@ -11,8 +11,17 @@
import { readFileSync, readdirSync, statSync } from "node:fs";
import { join, relative } from "node:path";
import { parse as parseYaml, YAMLParseError } from "yaml";
const SKILLS_DIR = join(import.meta.dirname, "..", "skills");
const REPO_ROOT = join(import.meta.dirname, "..");
// Every location that ships SKILL.md files gets linted. `skills/` is the
// marketplace-distributed set; `.claude/skills/` and `.agents/skills/` are the
// repo-native project skills auto-discovered by Claude Code and Codex CLI.
const SKILLS_DIRS = [
join(REPO_ROOT, "skills"),
join(REPO_ROOT, ".claude", "skills"),
join(REPO_ROOT, ".agents", "skills"),
];
interface Violation {
file: string;
@@ -66,31 +75,160 @@ function collectSkillFiles(dir: string): string[] {
* mappings"). Not a full YAML parse; if a different malformation appears,
* swap this for a real parser (the `yaml` package).
*/
function lintFrontmatter(content: string): Omit<Violation, "file">[] {
const match = content.match(/^---\n([\s\S]*?)\n---/);
if (!match) return [];
const violations: Omit<Violation, "file">[] = [];
const fmLines = match[1].split("\n");
for (let i = 0; i < fmLines.length; i++) {
const line = fmLines[i];
// Top-level `key: value` (no indentation). Skip block scalars (> |),
// already-quoted values, and flow collections — those handle colons fine.
const m = line.match(/^([A-Za-z0-9_-]+):[ \t]+(.+)$/);
if (!m) continue;
const value = m[2].trim();
if (/^["'>|[{]/.test(value)) continue;
if (/:[ \t]/.test(value)) {
violations.push({
line: i + 2, // +1 for the opening `---`, +1 for 1-based
message:
`Unquoted frontmatter value for "${m[1]}" contains ": " — YAML reads ` +
`this as a nested mapping and the parse fails, which aborts ` +
`\`skills add\` for the entire repo. Quote the value or rephrase the colon.`,
text: line.trim(),
});
// SKILL.md frontmatter schema.
//
// Two required top-level string keys plus three optional ones. Parsed with a
// real YAML parser (the `yaml` npm package) so we can validate value TYPES
// (name/description must be strings, allowed-tools must be a sequence or
// string, metadata must be a mapping), not just line-level patterns.
//
// This is a NECESSARY-but-not-SUFFICIENT gate. Catches:
// * unsupported top-level keys (e.g. `category:`)
// * missing name / description
// * malformed YAML
// * type errors (name is a list; description is a number; metadata is a scalar)
// * empty string values
//
// The canonical Claude Code / Codex CLI / marketplace loaders may enforce
// stricter rules (name regex, description length, nested-schema shape); those
// are validated at load / install time. Positive + negative fixtures live in
// scripts/lint-skills.test.mjs.
const REQUIRED_FRONTMATTER_KEYS = new Set(["name", "description"]);
const OPTIONAL_FRONTMATTER_KEYS = new Set(["license", "allowed-tools", "metadata"]);
const KNOWN_FRONTMATTER_KEYS = new Set([
...REQUIRED_FRONTMATTER_KEYS,
...OPTIONAL_FRONTMATTER_KEYS,
]);
type LineViolation = Omit<Violation, "file">;
function violation(line: number, message: string, text: string): LineViolation {
return { line, message, text };
}
function isPlainObject(v: unknown): v is Record<string, unknown> {
return typeof v === "object" && v !== null && !Array.isArray(v);
}
function parseFrontmatterYaml(body: string): { data?: unknown; error?: string } {
try {
return { data: parseYaml(body) };
} catch (err) {
if (err instanceof YAMLParseError) {
return { error: err.message };
}
return { error: err instanceof Error ? err.message : String(err) };
}
return violations;
}
function typeLabel(v: unknown): string {
if (v === null) return "null";
if (Array.isArray(v)) return "list";
return typeof v;
}
function missingRequired(data: Record<string, unknown>): LineViolation[] {
return [...REQUIRED_FRONTMATTER_KEYS]
.filter((k) => !(k in data))
.map((k) => violation(-1, `Missing required frontmatter key "${k}".`, "<top of file>"));
}
function unsupportedKeys(data: Record<string, unknown>): LineViolation[] {
return Object.keys(data)
.filter((k) => !KNOWN_FRONTMATTER_KEYS.has(k))
.map((k) =>
violation(
-1,
`Unsupported frontmatter key "${k}" — SKILL.md accepts required { ` +
`${[...REQUIRED_FRONTMATTER_KEYS].join(", ")} } plus optional { ` +
`${[...OPTIONAL_FRONTMATTER_KEYS].join(", ")} }.`,
`${k}: ...`,
),
);
}
function stringFieldError(key: string, value: unknown, allowEmpty: boolean): LineViolation | null {
if (typeof value !== "string") {
return violation(
-1,
`Frontmatter "${key}" must be a string (got ${typeLabel(value)}).`,
`${key}: ${JSON.stringify(value)}`,
);
}
if (!allowEmpty && value.trim().length === 0) {
return violation(-1, `Frontmatter "${key}" must not be empty.`, `${key}: ""`);
}
return null;
}
function validateStringField(
data: Record<string, unknown>,
key: string,
allowEmpty: boolean,
): LineViolation | null {
return key in data ? stringFieldError(key, data[key], allowEmpty) : null;
}
function isValidAllowedTools(value: unknown): boolean {
if (typeof value === "string") return true;
return Array.isArray(value) && value.every((v) => typeof v === "string");
}
function validateAllowedTools(data: Record<string, unknown>): LineViolation | null {
if (!("allowed-tools" in data)) return null;
if (isValidAllowedTools(data["allowed-tools"])) return null;
return violation(
-1,
`Frontmatter "allowed-tools" must be a string or a list of strings.`,
`allowed-tools: ${JSON.stringify(data["allowed-tools"])}`,
);
}
function validateMetadata(data: Record<string, unknown>): LineViolation | null {
if (!("metadata" in data)) return null;
if (isPlainObject(data.metadata)) return null;
return violation(
-1,
`Frontmatter "metadata" must be a mapping / object.`,
`metadata: ${JSON.stringify(data.metadata)}`,
);
}
function validateShape(data: Record<string, unknown>): LineViolation[] {
const fieldChecks = [
validateStringField(data, "name", false),
validateStringField(data, "description", false),
validateStringField(data, "license", true),
validateAllowedTools(data),
validateMetadata(data),
].filter((v): v is LineViolation => v !== null);
return [...missingRequired(data), ...unsupportedKeys(data), ...fieldChecks];
}
function parsedDataError(parsed: { data?: unknown; error?: string }): LineViolation | null {
if (parsed.error) {
return violation(1, `Malformed YAML frontmatter: ${parsed.error}`, "<frontmatter block>");
}
if (isPlainObject(parsed.data)) return null;
return violation(
1,
`Frontmatter must be a YAML mapping at the top level (got ${typeLabel(parsed.data)}).`,
"<frontmatter block>",
);
}
export function lintFrontmatter(content: string): LineViolation[] {
const match = content.match(/^---\n([\s\S]*?)\n---/);
if (!match) {
return [
violation(1, `Missing SKILL.md YAML frontmatter (must start with '---').`, "<top of file>"),
];
}
const parsed = parseFrontmatterYaml(match[1]);
const preflightError = parsedDataError(parsed);
if (preflightError) return [preflightError];
return validateShape(parsed.data as Record<string, unknown>);
}
/** Strip fenced code blocks so we only lint prose + inline code. */
@@ -103,48 +241,41 @@ function stripFencedBlocks(content: string): string {
);
}
function matchDangerousPatterns(file: string, line: string, lineNumber: number): Violation[] {
return DANGEROUS_INLINE_PATTERNS.filter((p) => p.pattern.test(line)).map((p) => ({
file,
line: lineNumber,
message: p.message,
text: line.trim(),
}));
}
function lintInlinePatterns(file: string, stripped: string): Violation[] {
return stripped
.split("\n")
.flatMap((line, i) => (line ? matchDangerousPatterns(file, line, i + 1) : []));
}
function lintFile(filePath: string): Violation[] {
const raw = readFileSync(filePath, "utf-8");
const file = relative(process.cwd(), filePath);
const violations: Violation[] = lintFrontmatter(raw).map((v) => ({
...v,
file,
}));
const stripped = stripFencedBlocks(raw);
const lines = stripped.split("\n");
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
if (!line) continue;
for (const { pattern, message } of DANGEROUS_INLINE_PATTERNS) {
if (pattern.test(line)) {
violations.push({
file: relative(process.cwd(), filePath),
line: i + 1,
message,
text: line.trim(),
});
}
}
}
return violations;
return [
...lintFrontmatter(raw).map((v) => ({ ...v, file })),
...lintInlinePatterns(file, stripFencedBlocks(raw)),
];
}
// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------
if (!statSync(SKILLS_DIR, { throwIfNoEntry: false })?.isDirectory()) {
console.log("No skills/ directory found — skipping skill lint.");
process.exit(0);
const files: string[] = [];
for (const dir of SKILLS_DIRS) {
if (!statSync(dir, { throwIfNoEntry: false })?.isDirectory()) continue;
files.push(...collectSkillFiles(dir));
}
const files = collectSkillFiles(SKILLS_DIR);
if (files.length === 0) {
console.log("No SKILL.md files found.");
console.log("No SKILL.md files found across skills/, .claude/skills/, .agents/skills/.");
process.exit(0);
}