Use the CLI repository as the agent skill installation source

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
 

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
 

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)
 
 ## 導入せずに使う
 

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)
 
 ## 설치 없이 사용
 

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)
 
 ## 不安装也能使用
 

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")
+}

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/,
+  )
+})

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"),