Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(skill): restore Archify installation and hide contributor review skill

tt-a1i67c47c119ece
diff --git a/.agents/skills/archify-review/SKILL.md b/.agents/skills/archify-review/SKILL.md
index 68b98baa..d28b635c 100644
--- a/.agents/skills/archify-review/SKILL.md
+++ b/.agents/skills/archify-review/SKILL.md
@@ -1,6 +1,8 @@
---
name: archify-review
description: Review Archify issues, PRs, or code through value, cost, and impact to support evidence-based maintenance decisions. Use for issue triage, change reviews, and code quality assessments.
+metadata:
+ internal: true
---
# Archify Review
diff --git a/archify.zip b/archify.zip
index fbd49493..4732481f 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 4ab91141..dc1e94c1 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -1,6 +1,6 @@
---
name: archify
-description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid. Also use for everyday subjects with steps, parts, relationships, or states: a leave or travel plan, an application or approval process, a back-and-forth such as renting, where money or documents go, or where an application or order stands. Not for numeric charts or dashboards.
+description: "Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid. Also use for everyday subjects with steps, parts, relationships, or states: a leave or travel plan, an application or approval process, a back-and-forth such as renting, where money or documents go, or where an application or order stands. Not for numeric charts or dashboards."
license: MIT
metadata:
version: "3.0"
diff --git a/archify/package-lock.json b/archify/package-lock.json
index 348d6893..f59e3252 100644
--- a/archify/package-lock.json
+++ b/archify/package-lock.json
@@ -15,12 +15,27 @@
"ajv": "^8.17.1",
"parse5": "7.3.0",
"saxes": "6.0.0",
- "simple-icons": "16.28.0"
+ "simple-icons": "16.28.0",
+ "skills": "1.7.0",
+ "yaml": "2.9.1"
},
"engines": {
"node": ">=18"
}
},
+ "node_modules/@isaacs/fs-minipass": {
+ "version": "4.0.1",
+ "resolved": "https://registry.npmjs.org/@isaacs/fs-minipass/-/fs-minipass-4.0.1.tgz",
+ "integrity": "sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==",
+ "dev": true,
+ "license": "ISC",
+ "dependencies": {
+ "minipass": "^7.0.4"
+ },
+ "engines": {
+ "node": ">=18.0.0"
+ }
+ },
"node_modules/ajv": {
"version": "8.20.0",
"resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
@@ -38,6 +53,16 @@
"url": "https://github.com/sponsors/epoberezkin"
}
},
+ "node_modules/chownr": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz",
+ "integrity": "sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==",
+ "dev": true,
+ "license": "BlueOak-1.0.0",
+ "engines": {
+ "node": ">=18"
+ }
+ },
"node_modules/entities": {
"version": "6.0.1",
"resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
@@ -82,6 +107,29 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/minipass": {
+ "version": "7.1.3",
+ "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
+ "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
+ "dev": true,
+ "license": "BlueOak-1.0.0",
+ "engines": {
+ "node": ">=16 || 14 >=14.17"
+ }
+ },
+ "node_modules/minizlib": {
+ "version": "3.1.0",
+ "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz",
+ "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "minipass": "^7.1.2"
+ },
+ "engines": {
+ "node": ">= 18"
+ }
+ },
"node_modules/parse5": {
"version": "7.3.0",
"resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz",
@@ -138,12 +186,73 @@
"node": ">=0.12.18"
}
},
+ "node_modules/skills": {
+ "version": "1.7.0",
+ "resolved": "https://registry.npmjs.org/skills/-/skills-1.7.0.tgz",
+ "integrity": "sha512-OfePnDft+Xt9/tCoHdCUe5fkM8i+Q3QOSQO53hm7mKtsXyvc+CKOAAliVWZ484HS3cWx+6r+ob0AArixs3jYXw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "tar": "^7.5.20",
+ "yaml": "^2.8.3"
+ },
+ "bin": {
+ "add-skill": "bin/cli.mjs",
+ "skills": "bin/cli.mjs"
+ },
+ "engines": {
+ "node": ">=22.20.0"
+ }
+ },
+ "node_modules/tar": {
+ "version": "7.5.22",
+ "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.22.tgz",
+ "integrity": "sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==",
+ "dev": true,
+ "license": "BlueOak-1.0.0",
+ "dependencies": {
+ "@isaacs/fs-minipass": "^4.0.0",
+ "chownr": "^3.0.0",
+ "minipass": "^7.1.2",
+ "minizlib": "^3.1.0",
+ "yallist": "^5.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
"node_modules/xmlchars": {
"version": "2.2.0",
"resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
"integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
"dev": true,
"license": "MIT"
+ },
+ "node_modules/yallist": {
+ "version": "5.0.0",
+ "resolved": "https://registry.npmjs.org/yallist/-/yallist-5.0.0.tgz",
+ "integrity": "sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==",
+ "dev": true,
+ "license": "BlueOak-1.0.0",
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/yaml": {
+ "version": "2.9.1",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
+ "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==",
+ "dev": true,
+ "license": "ISC",
+ "bin": {
+ "yaml": "bin.mjs"
+ },
+ "engines": {
+ "node": ">= 14.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/eemeli"
+ }
}
}
}
diff --git a/archify/package.json b/archify/package.json
index 6d2ab914..82db0c6f 100644
--- a/archify/package.json
+++ b/archify/package.json
@@ -32,7 +32,9 @@
"ajv": "^8.17.1",
"parse5": "7.3.0",
"saxes": "6.0.0",
- "simple-icons": "16.28.0"
+ "simple-icons": "16.28.0",
+ "skills": "1.7.0",
+ "yaml": "2.9.1"
},
"overrides": {
"fast-uri": "^3.1.7"
diff --git a/archify/test/skill-installation.test.mjs b/archify/test/skill-installation.test.mjs
new file mode 100644
index 00000000..33c30f4a
--- /dev/null
+++ b/archify/test/skill-installation.test.mjs
@@ -0,0 +1,142 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { stageCleanSkill } from '../../scripts/stage-clean-skill.mjs';
+
+const require = createRequire(import.meta.url);
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const skillsPackage = require.resolve('skills/package.json');
+const skillsCli = path.join(path.dirname(skillsPackage), 'bin', 'cli.mjs');
+const [major, minor] = process.versions.node.split('.').map(Number);
+// Archify supports Node 18+, while this external installer's own minimum is 22.20.
+// CI's Node 22 and 24 lanes exercise the real CLI; metadata tests run on all lanes.
+const installerSkip = major > 22 || (major === 22 && minor >= 20)
+ ? false : 'skills 1.7.0 requires Node >=22.20.0';
+
+function metadata(content) {
+ const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+ assert.ok(match, 'Skill must start with delimited YAML frontmatter');
+ const data = parse(match[1]);
+ assert.equal(data.name, 'archify');
+ assert.equal(typeof data.description, 'string');
+ assert.ok(data.description.trim());
+ return data;
+}
+
+function extractArchive(destination) {
+ fs.mkdirSync(destination, { recursive: true });
+ const archive = path.join(repoRoot, 'archify.zip');
+ const result = process.platform === 'win32'
+ ? spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+ 'Expand-Archive -LiteralPath $env:ARCHIFY_TEST_ARCHIVE -DestinationPath $env:ARCHIFY_TEST_EXTRACT'], {
+ encoding: 'utf8',
+ env: { ...process.env, ARCHIFY_TEST_ARCHIVE: archive, ARCHIFY_TEST_EXTRACT: destination },
+ })
+ : spawnSync('unzip', ['-q', archive, '-d', destination], { encoding: 'utf8' });
+ assert.equal(result.status, 0, result.error?.message || result.stderr);
+}
+
+test('distributed ZIP carries the same valid Skill frontmatter as source', (t) => {
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-frontmatter-'));
+ t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+ extractArchive(tmp);
+ const source = fs.readFileSync(path.join(repoRoot, 'archify', 'SKILL.md'), 'utf8');
+ const packaged = fs.readFileSync(path.join(tmp, 'archify', 'SKILL.md'), 'utf8');
+ assert.equal(packaged, source, 'rebuild archify.zip when Skill instructions change');
+ assert.deepEqual(metadata(packaged), metadata(source));
+ assert.deepEqual(metadata(packaged.replace(/\r?\n/g, '\r\n')), metadata(source));
+});
+
+test('real Skills CLI keeps source and ZIP installs scoped to the requested Skill', {
+ skip: installerSkip,
+}, async (t) => {
+ assert.equal(JSON.parse(fs.readFileSync(skillsPackage, 'utf8')).version, '1.7.0');
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-skills-install-'));
+ t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+ const source = path.join(tmp, 'source');
+ const archive = path.join(tmp, 'archive');
+ // Use the repository's tracked-file stager: no node_modules, local Skills,
+ // symlinks, or other developer files enter the installation source.
+ stageCleanSkill({ repoRoot, destination: path.join(source, 'archify') });
+ const review = '.agents/skills/archify-review/SKILL.md';
+ fs.mkdirSync(path.dirname(path.join(source, review)), { recursive: true });
+ fs.copyFileSync(path.join(repoRoot, review), path.join(source, review));
+ extractArchive(archive);
+ let sequence = 0;
+ function invoke(sourcePath, flags) {
+ const cwd = path.join(tmp, `target-${sequence++}`);
+ fs.mkdirSync(cwd);
+ const result = spawnSync(process.execPath, [skillsCli, 'add', sourcePath, ...flags], {
+ cwd, encoding: 'utf8', timeout: 30_000,
+ env: {
+ ...process.env, INSTALL_INTERNAL_SKILLS: '0',
+ DISABLE_TELEMETRY: '1', DO_NOT_TRACK: '1', NODE_DISABLE_COMPILE_CACHE: '1',
+ XDG_STATE_HOME: path.join(tmp, 'state'), NO_COLOR: '1',
+ },
+ });
+ const output = `${result.stdout || ''}\n${result.stderr || ''}`
+ .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+ assert.ifError(result.error);
+ return { ...result, cwd, output };
+ }
+ function installedNames(cwd) {
+ const directory = path.join(cwd, '.agents', 'skills');
+ return fs.existsSync(directory) ? fs.readdirSync(directory).sort() : [];
+ }
+ function install(sourcePath, selection = []) {
+ return invoke(sourcePath, [...selection, '--agent', 'codex', '--copy', '--yes']);
+ }
+ for (const [label, sourcePath] of [['source', source], ['ZIP', archive]]) {
+ await t.test(`${label}: default and full-depth discovery expose only archify`, () => {
+ for (const flags of [['--list'], ['--list', '--full-depth']]) {
+ const result = invoke(sourcePath, flags);
+ assert.equal(result.status, 0, result.output);
+ assert.match(result.output, /Found 1 skill\b/);
+ assert.match(result.output, /Available Skills[\s\S]*\barchify\b/);
+ assert.doesNotMatch(result.output, /archify-review|YAML parse error/);
+ assert.deepEqual(installedNames(result.cwd), []);
+ }
+ });
+ await t.test(`${label}: explicit and unfiltered --yes installs copy only archify`, () => {
+ for (const selection of [['--skill', 'archify'], [], ['--skill', '*']]) {
+ const result = install(sourcePath, selection);
+ assert.equal(result.status, 0, result.output);
+ assert.deepEqual(installedNames(result.cwd), ['archify']);
+ const lock = JSON.parse(fs.readFileSync(path.join(result.cwd, 'skills-lock.json'), 'utf8'));
+ assert.deepEqual(Object.keys(lock.skills), ['archify']);
+ const installed = path.join(result.cwd, '.agents', 'skills', 'archify');
+ metadata(fs.readFileSync(path.join(installed, 'SKILL.md'), 'utf8'));
+ assert.equal(fs.lstatSync(installed).isSymbolicLink(), false);
+ const doctor = spawnSync(process.execPath, [path.join(installed, 'bin', 'archify.mjs'), 'doctor'], {
+ cwd: installed, encoding: 'utf8', timeout: 30_000,
+ env: { ...process.env, ARCHIFY_UPDATE_CHECK_DISABLED: '1' },
+ });
+ assert.equal(doctor.status, 0, doctor.stderr);
+ assert.match(doctor.stdout, /Archify is ready\./);
+ }
+ });
+ }
+ await t.test('maintainers can still explicitly select the internal review Skill', () => {
+ const result = install(source, ['--skill', 'archify-review']);
+ assert.equal(result.status, 0, result.output);
+ assert.deepEqual(installedNames(result.cwd), ['archify-review']);
+ });
+ await t.test('malformed frontmatter fails without falling back to review or writing a lock', () => {
+ const file = path.join(source, 'archify', 'SKILL.md');
+ fs.writeFileSync(file, fs.readFileSync(file, 'utf8').replace(/^description:.*$/m,
+ 'description: steps and states: a plan'));
+ for (const selection of [['--skill', 'archify'], []]) {
+ const result = install(source, selection);
+ assert.equal(result.status, 1, result.output);
+ assert.match(result.output, /YAML parse error/);
+ assert.deepEqual(installedNames(result.cwd), []);
+ assert.equal(fs.existsSync(path.join(result.cwd, 'skills-lock.json')), false);
+ }
+ });
+});
diff --git a/archify/test/skill-metadata.test.mjs b/archify/test/skill-metadata.test.mjs
index 335b1e9a..ca506e6a 100644
--- a/archify/test/skill-metadata.test.mjs
+++ b/archify/test/skill-metadata.test.mjs
@@ -3,6 +3,7 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import test from 'node:test';
import assert from 'node:assert/strict';
+import { parse } from 'yaml';
const here = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.join(here, '..');
@@ -10,12 +11,15 @@ const skill = readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');
const defaults = readFileSync(path.join(skillRoot, 'references', 'authoring-defaults.md'), 'utf8');
const updateAwareness = readFileSync(path.join(skillRoot, 'references', 'update-awareness.md'), 'utf8');
const authoringContract = readFileSync(path.join(skillRoot, 'references', 'authoring-contract.md'), 'utf8');
-const frontmatter = skill.match(/^---\n([\s\S]*?)\n---/);
+const frontmatter = skill.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
test('skill description is portable across 1024-character runtimes and remains searchable', () => {
assert.ok(frontmatter, 'SKILL.md must start with YAML frontmatter');
- const description = frontmatter[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
- assert.ok(description, 'frontmatter must include a one-line description');
+ const metadata = parse(frontmatter[1]);
+ assert.equal(metadata.name, 'archify');
+ const description = metadata.description;
+ assert.equal(typeof description, 'string', 'frontmatter description must be a YAML string');
+ assert.ok(description.trim(), 'frontmatter must include a nonempty description');
assert.ok(description.length <= 1024, `description is ${description.length} characters; maximum is 1024`);
assert.ok(Buffer.byteLength(description, 'utf8') <= 1024, 'description must also fit a 1024-byte runtime limit');
@@ -84,3 +88,17 @@ test('skill keeps the title hierarchy compact by default', () => {
assert.match(authoringContract, /never use it to restate the title, nodes, edges,\s+or cards/);
assert.match(authoringContract, /omitted or blank subtitle must not leave an empty visual row/);
});
+
+// The review Skill remains available to repository maintainers, but must not
+// enter an unfiltered consumer install from the repository root.
+test('contributor review skill is internal and retains its repository references', () => {
+ const reviewRoot = path.resolve(skillRoot, '..', '.agents', 'skills', 'archify-review');
+ const review = readFileSync(path.join(reviewRoot, 'SKILL.md'), 'utf8');
+ const metadata = parse(review.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)[1]);
+ assert.equal(metadata.name, 'archify-review');
+ assert.equal(metadata.metadata?.internal, true);
+ for (const document of ['../../../REVIEWING.md', '../../../CONTRIBUTING.md']) {
+ assert.ok(review.includes(document));
+ assert.ok(existsSync(path.resolve(reviewRoot, document)));
+ }
+});