跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

shipping-artifacts

Documenting an AI-built app for handoff, review or audit: the docs that make it reviewable (architecture, flows, permissions, variables, coverage).

phuryn · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add phuryn/product-engineering --skill shipping-artifacts

技能说明


name: shipping-artifacts description: "Documenting an AI-built app for handoff, review or audit: the docs that make it reviewable (architecture, flows, permissions, variables, coverage)."

Shipping Artifacts: The Docs That Make AI-Built Code Reviewable

Purpose

AI agents write code fast, but they leave no durable record of intent — what the system is supposed to do, who is allowed to do what, where the secrets live, which rules are actually verified. Without that record, no human (and no auditing agent) can tell whether the code is safe to ship. This skill defines the small set of documents that restore reviewability.

These docs are written for two readers: a human reviewer and the next AI coding agent. They are the intended-state half of every later audit — a security or performance review is only as good as the intent it can compare the code against.

Locations and names: the repo's setup wins

Every location, file name and doc-format convention in this plugin is a default. The host repo's own setup comes first. Before writing anything (a system doc, the coverage map, an audit report), look for that setup:

  1. Agent instructions — AGENTS.md, CLAUDE.md, and whatever they import or point to. They often name the docs folder, the files in it, who maintains each one, and how dates are recorded.
  2. A docs location — an existing docs/, documentation/ or similar folder.
  3. Existing equivalents — a document that already covers what one of the files below covers, under any name (ARCHITECTURE.md, docs/security.md, docs/env.md). Match on what it covers, not on its file name.
  4. An existing test-coverage map — a file that maps behaviour to the tests covering it, such as docs/test-coverage.md. Match on what it covers: a TESTS.md or testing.md that describes how the repo tests is the testing method, not the coverage map.
  5. A reports location — wherever the repo already keeps audit or review output.

Then:

  • Follow what you find. Write into the repo's docs location, update its existing equivalent instead of creating a parallel file, and keep its naming and date conventions. What each document must contain does not change; only where it lives and what it is called. If its agent instructions say how or by whom a doc is maintained, follow that too.
  • Use the plugin's defaults only where the repo has none: docs in documentation/ at the repo root, the file names below, the coverage map at documentation/tests.md, reports at reports/<name>_{timestamp}.md, and no "updated date" line (the file's history is the source of truth).
  • Say which you did. The output names every location and file written, and whether each follows the repo's setup or a plugin default.
  • Never create a file whose name differs from an existing one only in letter case — tests.md beside TESTS.md, Architecture.md beside architecture.md. On Windows and macOS they are the same file, so the write overwrites it; elsewhere they become two files that collide on the next checkout. Check case-insensitively before creating a file. If the existing one covers the same thing, use it. If it covers something else (a TESTS.md that is the testing method, not a coverage map), do not write into it: use the repo's real equivalent, and where there is none, pick a name that collides with nothing.

Throughout this plugin, a name such as architecture.md or tests.md means that document, wherever and under whatever name the repo keeps it.

How the set is organized

The set is not a fixed list — it is a small core plus conditional docs you add only when the capability exists.

  • Core docs — every reviewable app has these surfaces, so always produce them.
  • Conditional docs — include one only if the app actually has that capability. If it doesn't, write a single line in architecture.md ("No scheduled work — no cron.md.") rather than inventing an empty document. Reviewability comes from an honest map, and "we don't do X" is part of the map.
  • Most docs are reverse-engineered from code by the document-app skill. The one exception is tests.md, which is derived from the other docs by the derive-tests skill — it is the verification map, not a description of a subsystem.

Be brutally honest about the current state without being paranoid. The job is an accurate map, not a clean bill of health. Each doc is short, table-and-bullet heavy, and skips generic theory.

Core documents

Each entry: default file name · one-line purpose · what it must capture · how a reviewer uses it.

  1. architecture.md — what the system is and how it hangs together.

    • Must capture: product overview + key assumptions; tech stack; how auth/sessions/claims flow end to end; the trust boundaries (e.g. service-role vs. client); a short Known risks / assumptions list (each entry backed by where it shows up in the code, not a generic checklist); a "Related Documents" index of every other doc produced.
    • Reviewer use: the root document — everything else is cross-referenced from here.
  2. flows.md — the journeys where permissions and side effects are actually exercised.

    • Must capture: each load-bearing flow as actor + precondition + success outcome; the step-by-step sequence across UI → server → data → jobs → providers → agents; the authz check at each protected step (which claim/role/scope, on which resource, and the expected deny case); the trust-boundary crossings (browser→server, server→provider, job→app, agent→tool, webhook→app); the state changes and side effects each step causes (writes, emails queued, jobs triggered, outbound calls).
    • Reviewer use: the runtime view a static permissions.md matrix can't show — where and in what order authorization is enforced, and where it can be skipped.
    • Anti-PRD rule: a flow that doesn't touch permissions, data integrity, external side effects, money, privacy, or operati
阅读完整来源 ↗