GaZmagik/iso-24495 / skills/iso-24495-5
iso-24495-5
FlaggedProvisional sector-specific Plain Language standard for document design (based on ISO/WD 24495-5, under development). Applied when structuring complex documents so readers can find and navigate content through layout, visual hierarchy, and navigation aids.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.5 KB |
| agents/openai.yaml | config | 283 B |
| assets/adr-template.md | markdown | 1.2 KB |
| assets/design-doc-template.md | markdown | 2.7 KB |
| assets/runbook-template.md | markdown | 741 B |
| tests/fixtures/pinned-documents.ts | script | 198.8 KB |
| tests/reference/build-pinned-documents.ts | script | 2.4 KB |
| tests/reference/shipped-documents.ts | script | 2.5 KB |
| tests/repository-conventions.test.ts | script | 107.1 KB |
| tests/skill-frontmatter.test.ts | script | 4.0 KB |
| tests/templates.test.ts | script | 17.9 KB |
tests/skill-frontmatter.test.ts
View on GitHub/**
* Parse every skill's frontmatter, because a plugin whose manifest will not load ships silently.
*
* v0.6.0 shipped `iso-24495-code` with an unquoted description containing a colon and a space:
*
* description: ... Governs the parts of code a person reads: the order units appear in, ...
*
* YAML reads that as the start of a nested mapping, so the loader refused the file with "mapping
* values are not allowed in this context at line 2 column 123". Column 123 is the colon.
*
* The repository gate did not notice, because nothing here had ever parsed a SKILL.md as YAML. It
* checked the prose inside the file and the files beside it, and took the frontmatter on trust.
* Every other test in this suite reads these files as text, which is exactly why this one must
* not.
*/
import { describe, expect, test } from "bun:test";
import { readFileSync, readdirSync, statSync } from "node:fs";
import { join } from "node:path";
const ROOT = join(import.meta.dir, "..", "..", "..");
const ROOTS = ["skills", "codex-skills"];
/** Every SKILL.md in the repository, by its path relative to the root. */
function skillFiles(): string[] {
const found: string[] = [];
for (const directory of ROOTS) {
const base = join(ROOT, directory);
let entries: string[];
try {
entries = readdirSync(base);
} catch {
continue;
}
for (const entry of entries) {
const path = join(base, entry, "SKILL.md");
try {
if (statSync(path).isFile()) found.push(`${directory}/${entry}/SKILL.md`);
} catch {
// A directory without a SKILL.md is not a skill.
}
}
}
return found.sort();
}
/** The text between the opening and closing fence, which is what a loader hands to YAML. */
function frontmatter(relativePath: string): string {
const text = readFileSync(join(ROOT, relativePath), "utf8");
const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
if (match === null) throw new Error(`${relativePath}: no frontmatter fence`);
return match[1] as string;
}
describe("every skill's frontmatter", () => {
const files = skillFiles();
test("there are skills to check", () => {
// A test that finds nothing passes, and proves nothing. This is the counting guard.
expect(files.length).toBeGreaterThanOrEqual(7);
});
test("parses as YAML", () => {
// The failure this file exists for. An unquoted colon and space breaks the parse.
const broken: string[] = [];
for (const file of files) {
try {
Bun.YAML.parse(frontmatter(file));
} catch (error) {
broken.push(`${file}: ${(error as Error).message}`);
}
}
expect(broken).toEqual([]);
});
test("gives a loader the name and description it needs", () => {
for (const file of files) {
const parsed = Bun.YAML.parse(frontmatter(file)) as Record<string, unknown>;
expect(typeof parsed.name, `${file} name`).toBe("string");
expect(typeof parsed.description, `${file} description`).toBe("string");
expect((parsed.name as string).length, `${file} name is not empty`).toBeGreaterThan(0);
expect((parsed.description as string).length, `${file} description is not empty`)
.toBeGreaterThan(0);
}
});
test("names the skill after the directory holding it", () => {
for (const file of files) {
const parsed = Bun.YAML.parse(frontmatter(file)) as Record<string, unknown>;
const directory = file.split("/")[1];
expect(parsed.name, file).toBe(directory);
}
});
test("a colon in a description is caught rather than shipped", () => {
// Proves the parse test can fail, against the exact text v0.6.0 shipped. Without this, a
// parser that quietly accepted anything would pass the test above for ever.
const shipped = 'name: iso-24495-code\n'
+ 'description: Governs the parts of code a person reads: the order units appear in.\n';
expect(() => Bun.YAML.parse(shipped)).toThrow();
expect(() => Bun.YAML.parse('name: a\ndescription: "reads: the order"\n')).not.toThrow();
});
});
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |