From 7bff7b819295b9d2cd708ea1128977efbc62dfa4 Mon Sep 17 00:00:00 2001 From: konojunya Date: Sun, 6 Sep 2026 01:51:18 +0900 Subject: [PATCH] Use the CLI-owned agent skill and verify its pinned content --- README.md | 2 +- docs/guide/coding-agents.md | 4 +-- docs/ja/guide/coding-agents.md | 4 +-- docs/ko/guide/coding-agents.md | 4 +-- docs/zh/guide/coding-agents.md | 4 +-- scripts/agent-skill.mjs | 26 +++++++++++++++++++ scripts/agent-skill.test.mjs | 34 +++++++++++++++++++++++++ scripts/validate-docs-cli.mjs | 3 ++- skills/stack-diagrams/SKILL.md | 46 ---------------------------------- 9 files changed, 71 insertions(+), 56 deletions(-) create mode 100644 scripts/agent-skill.mjs create mode 100644 scripts/agent-skill.test.mjs delete mode 100644 skills/stack-diagrams/SKILL.md diff --git a/README.md b/README.md index 591c79f..8ef4ec5 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ The required CI baseline compares the pin against GitHub's latest stable release ## Coding agent skill -Install the focused diagram skill with `npx skills add stack-sh/web --skill stack-diagrams` in the target project. It provides instructions, not a CLI binary. See the [coding agent guide](https://stack-diagram.com/docs/guide/coding-agents) for a copyable prompt, local validation loop, installation boundaries, and limitations. `skills/stack-diagrams/SKILL.md` is the maintained source; its CLI examples run alongside documentation examples against the published CLI in CI. +Install the focused diagram skill with `npx skills add stack-sh/cli` in the target project. It provides instructions, not a CLI binary. See the [coding agent guide](https://stack-diagram.com/docs/guide/coding-agents) for a copyable prompt, local validation loop, installation boundaries, and limitations. The CLI repository owns `skills/stack-diagrams/SKILL.md`; `scripts/agent-skill.mjs` pins its merged revision and SHA-256. CI fetches and verifies those exact bytes, then runs its CLI examples alongside documentation examples against the published CLI. Update this separate skill pin after reviewing a merged skill change; it is independent of the binary release pin. ## Playground features diff --git a/docs/guide/coding-agents.md b/docs/guide/coding-agents.md index de8d82d..60eee21 100644 --- a/docs/guide/coding-agents.md +++ b/docs/guide/coding-agents.md @@ -4,9 +4,9 @@ Use Stack with a coding agent to keep architecture diagrams as reviewable source ## Install the skill -Install only the diagram skill with `npx skills add stack-sh/web --skill stack-diagrams`. This installs into the current project; add `-g` only when you want a user-wide installation. Review the downloaded instructions before use. This installs instructions, not the Stack CLI. For a reproducible installation, clone the repository, check out a reviewed commit, then run `npx skills add /absolute/path/to/web --skill stack-diagrams`. The installer does not accept a raw commit SHA as a remote branch. +Install only the diagram skill with `npx skills add stack-sh/cli`. This installs into the current project; add `-g` only when you want a user-wide installation. Review the downloaded instructions before use. This installs instructions, not the Stack CLI. For a reproducible installation, clone the repository, check out a reviewed commit, then run `npx skills add /absolute/path/to/cli --skill stack-diagrams`. The installer does not accept a raw commit SHA as a remote branch. -[SKILL.md](https://github.com/stack-sh/web/blob/main/skills/stack-diagrams/SKILL.md) +[SKILL.md](https://github.com/stack-sh/cli/blob/main/skills/stack-diagrams/SKILL.md) ## Without installation diff --git a/docs/ja/guide/coding-agents.md b/docs/ja/guide/coding-agents.md index f827217..ad902a2 100644 --- a/docs/ja/guide/coding-agents.md +++ b/docs/ja/guide/coding-agents.md @@ -4,9 +4,9 @@ Coding agentでStackを読み書きすると、構成図をレビュー可能な ## Skillの導入 -`npx skills add stack-sh/web --skill stack-diagrams`で図作成skillだけをcurrent projectへ導入します。User全体へ導入したい場合だけ`-g`を付け、取得したinstructionを確認してください。CLI本体は別途必要です。再現可能な導入にはrepositoryをcloneして確認済みcommitをcheckoutし、`npx skills add /absolute/path/to/web --skill stack-diagrams`で導入します。Installerはcommit SHAをremote branchとして直接指定する方法には対応していません。 +`npx skills add stack-sh/cli`で図作成skillだけをcurrent projectへ導入します。User全体へ導入したい場合だけ`-g`を付け、取得したinstructionを確認してください。CLI本体は別途必要です。再現可能な導入にはrepositoryをcloneして確認済みcommitをcheckoutし、`npx skills add /absolute/path/to/cli --skill stack-diagrams`で導入します。Installerはcommit SHAをremote branchとして直接指定する方法には対応していません。 -[SKILL.md](https://github.com/stack-sh/web/blob/main/skills/stack-diagrams/SKILL.md) +[SKILL.md](https://github.com/stack-sh/cli/blob/main/skills/stack-diagrams/SKILL.md) ## 導入せずに使う diff --git a/docs/ko/guide/coding-agents.md b/docs/ko/guide/coding-agents.md index 59f5449..fa5f6da 100644 --- a/docs/ko/guide/coding-agents.md +++ b/docs/ko/guide/coding-agents.md @@ -4,9 +4,9 @@ Coding agent로 Stack을 읽고 쓰면 아키텍처 다이어그램을 검토 ## Skill 설치 -`npx skills add stack-sh/web --skill stack-diagrams`로 현재 프로젝트에 다이어그램 skill만 설치합니다. 사용자 전체에 설치하려는 경우에만 `-g`를 추가하고 다운로드한 지침을 검토하세요. CLI는 별도로 설치해야 합니다. 재현 가능한 설치에는 저장소를 clone하고 검토한 commit을 checkout한 다음 `npx skills add /absolute/path/to/web --skill stack-diagrams`를 실행하세요. 설치 프로그램은 commit SHA를 원격 브랜치로 직접 지정하는 방식을 지원하지 않습니다. +`npx skills add stack-sh/cli`로 현재 프로젝트에 다이어그램 skill만 설치합니다. 사용자 전체에 설치하려는 경우에만 `-g`를 추가하고 다운로드한 지침을 검토하세요. CLI는 별도로 설치해야 합니다. 재현 가능한 설치에는 저장소를 clone하고 검토한 commit을 checkout한 다음 `npx skills add /absolute/path/to/cli --skill stack-diagrams`를 실행하세요. 설치 프로그램은 commit SHA를 원격 브랜치로 직접 지정하는 방식을 지원하지 않습니다. -[SKILL.md](https://github.com/stack-sh/web/blob/main/skills/stack-diagrams/SKILL.md) +[SKILL.md](https://github.com/stack-sh/cli/blob/main/skills/stack-diagrams/SKILL.md) ## 설치 없이 사용 diff --git a/docs/zh/guide/coding-agents.md b/docs/zh/guide/coding-agents.md index e661784..67f8c12 100644 --- a/docs/zh/guide/coding-agents.md +++ b/docs/zh/guide/coding-agents.md @@ -4,9 +4,9 @@ ## 安装 skill -使用 `npx skills add stack-sh/web --skill stack-diagrams` 仅将图表 skill 安装到当前项目。仅在需要用户级安装时添加 `-g`，并检查下载的指令。CLI 需要单独安装。需要可复现安装时，先 clone 仓库并 checkout 已审核的 commit，再运行 `npx skills add /absolute/path/to/web --skill stack-diagrams`。安装器不能将 commit SHA 直接作为远程分支安装。 +使用 `npx skills add stack-sh/cli` 仅将图表 skill 安装到当前项目。仅在需要用户级安装时添加 `-g`，并检查下载的指令。CLI 需要单独安装。需要可复现安装时，先 clone 仓库并 checkout 已审核的 commit，再运行 `npx skills add /absolute/path/to/cli --skill stack-diagrams`。安装器不能将 commit SHA 直接作为远程分支安装。 -[SKILL.md](https://github.com/stack-sh/web/blob/main/skills/stack-diagrams/SKILL.md) +[SKILL.md](https://github.com/stack-sh/cli/blob/main/skills/stack-diagrams/SKILL.md) ## 不安装也能使用 diff --git a/scripts/agent-skill.mjs b/scripts/agent-skill.mjs new file mode 100644 index 0000000..6323841 --- /dev/null +++ b/scripts/agent-skill.mjs @@ -0,0 +1,26 @@ +import assert from "node:assert/strict" +import { createHash } from "node:crypto" + +export const agentSkill = { + repository: "stack-sh/cli", + revision: "2ffeff8a547f0c82dd70d98e6e1945dc5dd03365", + path: "skills/stack-diagrams/SKILL.md", + sha256: "1336fbf606df083c842c0b8decdf81e73b11ec237e62e8462da0896b44456082", +} + +export async function readAgentSkill(lock = agentSkill, fetchResource = fetch) { + assert.equal(lock.repository, "stack-sh/cli") + assert.match(lock.revision, /^[a-f0-9]{40}$/) + assert.equal(lock.path, "skills/stack-diagrams/SKILL.md") + assert.match(lock.sha256, /^[a-f0-9]{64}$/) + const url = `https://raw.githubusercontent.com/${lock.repository}/${lock.revision}/${lock.path}` + const response = await fetchResource(url, { signal: AbortSignal.timeout(15_000) }) + assert.ok(response.ok, `Unable to retrieve pinned agent skill: HTTP ${response.status}`) + const bytes = Buffer.from(await response.arrayBuffer()) + assert.equal( + createHash("sha256").update(bytes).digest("hex"), + lock.sha256, + "Agent skill integrity mismatch", + ) + return bytes.toString("utf8") +} diff --git a/scripts/agent-skill.test.mjs b/scripts/agent-skill.test.mjs new file mode 100644 index 0000000..7f3f30a --- /dev/null +++ b/scripts/agent-skill.test.mjs @@ -0,0 +1,34 @@ +import assert from "node:assert/strict" +import { createHash } from "node:crypto" +import test from "node:test" +import { agentSkill, readAgentSkill } from "./agent-skill.mjs" + +const source = "verified skill fixture\n" +const lock = { + ...agentSkill, + revision: "a".repeat(40), + sha256: createHash("sha256").update(source).digest("hex"), +} + +test("skill retrieval uses an immutable owner URL and verifies exact bytes", async () => { + const result = await readAgentSkill(lock, async (url) => { + assert.equal( + url, + `https://raw.githubusercontent.com/stack-sh/cli/${lock.revision}/skills/stack-diagrams/SKILL.md`, + ) + return new Response(source) + }) + assert.equal(result, source) +}) + +test("skill retrieval rejects mutable revisions, missing resources, and altered bytes", async () => { + await assert.rejects(readAgentSkill({ ...lock, revision: "main" })) + await assert.rejects( + readAgentSkill(lock, async () => new Response("missing", { status: 404 })), + /HTTP 404/, + ) + await assert.rejects( + readAgentSkill(lock, async () => new Response(source + "changed")), + /integrity mismatch/, + ) +}) diff --git a/scripts/validate-docs-cli.mjs b/scripts/validate-docs-cli.mjs index 17527b4..1fb6b34 100644 --- a/scripts/validate-docs-cli.mjs +++ b/scripts/validate-docs-cli.mjs @@ -7,6 +7,7 @@ import { promisify } from "node:util" import { validateDocumentationContract } from "./docs-contract.mjs" import { documentationContract } from "./docs-validation.config.mjs" +import { readAgentSkill } from "./agent-skill.mjs" const execute = promisify(execFile) const cli = process.env.STACK_CLI_BIN @@ -23,7 +24,7 @@ const { documents, cliExamples } = await validateDocumentationContract({ exceptions: documentationContract.exceptions, }) -const skill = await readFile("skills/stack-diagrams/SKILL.md", "utf8") +const skill = await readAgentSkill() assert.match(skill, /^---\nname: stack-diagrams\ndescription: .+\nlicense: Apache-2.0\n---/) const skillCommands = [...skill.matchAll(/```sh\n([\s\S]*?)```/g)].flatMap((match) => match[1].trim().split("\n"), diff --git a/skills/stack-diagrams/SKILL.md b/skills/stack-diagrams/SKILL.md deleted file mode 100644 index 5727171..0000000 --- a/skills/stack-diagrams/SKILL.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: stack-diagrams -description: Create or edit Stack (.stack) software architecture diagrams, validate them with the Stack CLI, and render SVG. Use for Stack diagrams or when a user chooses Stack for architecture documentation; not for infrastructure provisioning or unrelated programming stacks. -license: Apache-2.0 ---- - -# Stack diagrams - -Deliver editable `.stack` source and, when rendering is available, an SVG. Preserve the requested architecture and existing unrelated content. Stack describes architecture; it does not provision resources or execute application code. - -## Start with the available tools - -Run `stack --version` and `stack help` before selecting commands. Use the installed binary's help, not unreleased repository instructions. The published CLI 0.4.0 supports `check`, `fmt`, and `render`; it does not support their `--json` flags. A newer version may support additional options: verify them using `stack help `. - -If the CLI is missing, consult the [installation guide](https://stack-diagram.com/docs/guide/getting-started.md) and [release distribution contract](https://github.com/stack-sh/cli/blob/v0.4.0/docs/distribution.md). Install only when the user's authorization allows it. Otherwise provide source with an explicit validation gap; do not report it as checked. No remote source upload is required. - -## Read only the relevant reference - -Start with [syntax](https://stack-diagram.com/docs/language/syntax.md), [nodes and groups](https://stack-diagram.com/docs/language/nodes-and-groups.md), and [edges and layout](https://stack-diagram.com/docs/language/edges-and-layout.md) when the grammar is unfamiliar. Find complete examples in the [gallery](https://stack-diagram.com/docs/examples/index.md). The [documentation index](https://stack-diagram.com/docs/llms.txt) links the remaining references. If the client cannot fetch one resource, try its Markdown page or report the missing information rather than inventing syntax. - -Non-obvious constraints: - -- One `stack 1.0` declaration and one named `diagram`; node/group IDs are globally unique. -- Declare edges at diagram scope. Endpoints are node IDs, not labels or groups. -- Model technologies using labels and `detail`; choose semantic `kind` values from the reference. Do not invent properties such as coordinates, colors, or ports. -- Prefer automatic layout or `direction` initially. `order` controls relative cross-axis ordering, not execution sequence; add `rank` or `order` only when the user needs that constraint. References must be direct children of that layout scope. -- Do not guess vendor icon IDs. Consult [provider icons](https://stack-diagram.com/docs/guide/provider-icons.md), query `stack icons list`, and verify the required pack is installed. Import downloads and terms acceptance need appropriate user authorization. If no pack is available, use the semantic kind fallback and explain that branded artwork is absent. - -## Generate, validate, and render - -For a new diagram, start with the smallest complete source that preserves the requested components and relationships. For an edit, inspect the existing source first and retain unrelated nodes, edges, labels, and comments. - -Using the user's actual filenames: - -```sh -stack check architecture.stack -stack fmt architecture.stack -stack check architecture.stack -stack render architecture.stack -o architecture.svg -``` - -`fmt` changes the source in place; avoid unrelated formatting when it would obscure a narrowly requested edit. Rendering to a file may replace it, so honor existing artifact ownership. - -Read both the exit status and diagnostics. An exit code of zero can still carry warnings. Fix unknown references or invalid syntax from the diagnostic ranges; never remove requested architecture merely to make validation pass. Investigate layout warnings without treating an optional visual hint as a required semantic relationship. Missing-icon warnings mean the image rendered with a fallback, not that provider artwork was found. Bound repeated repair attempts and report a remaining blocker rather than silently weakening the task. - -After rendering, inspect the SVG visually when a suitable viewer is available. Compiler success does not prove readable layout. Confirm the requested nodes, boundaries, relationships, and labels remain present. Report the source/SVG paths, CLI version, validation result, and any unresolved warnings or unverified visual behavior.