ai-design-context 0.4.0 → 0.5.0

package/AGENTS.md

@@ -92,6 +92,10 @@ Use them when the task matches their role:
 - `skills/prompt-architect/SKILL.md` for graph-backed prompt structure and output contracts.
 - `skills/knowledge-graph-architect/SKILL.md` for schema, registry, generated indexes, relationships, and validation scope.
 - `skills/agent-context/SKILL.md` for focused graph retrieval before implementation or review.
+- `skills/design-understand/SKILL.md` for understanding an existing screen before UI changes.
+- `skills/visual-qa/SKILL.md` for browser/screenshot evidence and scoped visual QA.
+- `skills/responsive-check/SKILL.md` for executing viewport and responsive interaction checks.
+- `skills/accessibility-check/SKILL.md` for executing semantic and keyboard/state checks.
 
 These skill files are not registered knowledge objects yet. Do not add them to `registry/objects.json` until skill metadata migration is explicitly requested.
 

package/CHANGELOG.md

@@ -2,12 +2,26 @@
 
 ## Unreleased
 
+## v0.5.0 — Discoverable Design Skills And Browser QA
+
+- Adapt the four supplied UI checklist skills with standalone metadata, existing graph references, concrete browser/image workflows, and explicit evidence boundaries.
+- Add read-only `skills list` / `skills show` CLI commands with Markdown and JSON output.
+- Install missing namespaced `.agents/skills` launchers for all 20 bundled workflows through `init`, preserving existing local files.
+- Load current workflows from the pinned npm package so package updates do not overwrite customized launchers.
+- Append design/browser-review routing separately from the original context block for safe upgrades from `0.4.0`.
+- Extend initialization and packed-install verification for skill discovery, source retrieval, local customization, malformed markers, and symlink paths.
+- Document browser and image-model prerequisites, reproducible findings, scoped verdicts, and unverified coverage.
+
+## npm v0.4.0 — AI Design Context Package
+
 - Rename the project to AI Design Context and use `ai-design-context` as the package name; keep the GitHub URL at `dev-ik/ai-design-rules`.
 - Preserve historical releases, frozen benchmark evidence, stable graph identifiers, and schema URIs under their original names.
 - Package the complete graph and upstream evidence with a dependency-free Node.js 20+ CLI and an explicit publish allowlist.
 - Add `init` for preserving existing agent instructions and creating only missing templates, with repeated-run and symlink protections.
 - Add installed-package `context` retrieval with absolute reading paths while preserving the existing checkout CLI contract.
 - Verify offline installation and use of the actual npm tarball; run repository checks and tests before packing.
+- Publish the first npm package as `ai-design-context@0.4.0`; preserve the existing historical GitHub `v0.4.0` tag.
+- Add automatic npm publishing from matching GitHub Releases through OIDC Trusted Publishing, with validation-only manual runs.
 
 ## v0.4.0 — Focused Context And Applied Patterns
 

package/README.md

@@ -5,6 +5,7 @@
 <h1 align="center">AI Design Context</h1>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/ai-design-context"><img alt="npm version" src="https://img.shields.io/npm/v/ai-design-context.svg"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
   <a href="CHANGELOG.md"><img alt="Status: active" src="https://img.shields.io/badge/status-active-success.svg"></a>
   <a href="evidence/README.md"><img alt="Evidence: benchmark driven" src="https://img.shields.io/badge/evidence-benchmark--driven-orange.svg"></a>
@@ -82,6 +83,8 @@ The repository is built as a **schema-first knowledge graph** for both humans an
 - Research-driven design rules
 - Reusable product and UI patterns
 - AI agent skills
+- Discoverable project-local skill launchers and a `skills` CLI
+- Browser and image QA workflows with explicit capability and evidence limits
 - Validation tooling
 - Benchmark framework
 - DesignLint v0 for evidence-chain relationship checks
@@ -123,7 +126,7 @@ The first benchmark is **directional**, not conclusive, and serves as the starti
 
 AI Design Context ships as the dependency-free npm package `ai-design-context` with a CLI and a versioned knowledge graph. Requires **Node.js 20 or later**. The GitHub repository stays at [`dev-ik/ai-design-rules`](https://github.com/dev-ik/ai-design-rules).
 
-After the first npm publication:
+Install the published package:
 
 ```bash
 npm install --save-dev --save-exact ai-design-context
@@ -131,7 +134,7 @@ npx ai-design-context init
 npx ai-design-context context --task quick-capture --platform mobile --intent implement
 ```
 
-Commit the project's dependency manifest and lockfile to pin the knowledge version. Installation alone does not edit project files: `init` explicitly appends a marked section to `AGENTS.md` and creates only missing product-context docs, feature/task templates, and review/benchmark checklists. It preserves existing instructions, populated files, and edited integration blocks; repeated runs do not duplicate them. Fill new placeholders with actual product context.
+Commit the project's dependency manifest and lockfile to pin the knowledge version. Installation alone does not edit project files: `init` explicitly appends marked context and design-review sections to `AGENTS.md` and creates only missing product-context docs, feature/task templates, review/benchmark checklists, and namespaced `.agents/skills` launchers. It preserves existing instructions, populated files, and edited integration blocks; repeated runs do not duplicate them. Fill new placeholders with actual product context.
 
 `context` reads the graph from the installed package, independently of the project's working directory. Markdown provides absolute reading paths; JSON adds `knowledgeRoot` and each object's `absolutePath` while preserving graph-relative `path`. Read the selected research and rules before implementing UI changes.
 
@@ -139,10 +142,14 @@ Commit the project's dependency manifest and lockfile to pin the knowledge versi
 npx ai-design-context context --object PAT-00002 --format json
 npx ai-design-context context --review REF-00001 --intent qa
 npx ai-design-context --help
+npx ai-design-context skills list
+npx ai-design-context skills show visual-qa
 ```
 
 Review queries retrieve matching graph knowledge; they do not analyze arbitrary application files. Matching is lexical, with known IDs and slugs available when phrases do not match. See [Agent Context](docs/AGENT_CONTEXT.md).
 
+After UI work, the installed skills guide browser interaction, screenshot inspection, responsive checks, and accessibility checks before final design review. Use the agent's browser tools or the project's Playwright setup and an image-capable model. The npm package supplies workflows and graph context; it does not provision browser binaries, connectors, or model vision. See [Design and Browser QA](docs/BROWSER_DESIGN_QA.md) for capability requirements and evidence reporting.
+
 Before publication, build a local tarball from this repository and install it into a product repository:
 
 ```bash
@@ -150,7 +157,7 @@ Before publication, build a local tarball from this repository and install it in
 npm pack
 
 # In the product repository; replace the path with the generated tarball path.
-npm install --save-dev /path/to/ai-design-context-0.4.0.tgz
+npm install --save-dev /path/to/ai-design-context-0.5.0.tgz
 npx ai-design-context init
 ```
 

package/RELEASE_NOTES_v0.5.0.md

@@ -0,0 +1,31 @@
+# AI Design Context v0.5.0
+
+This release connects the installed knowledge graph to discoverable design workflows and concrete browser/image QA.
+
+## Included
+
+- Adapt four supplied checklist skills: `design-understand`, `visual-qa`, `responsive-check`, and `accessibility-check`, with metadata, graph grounding, tool requirements, and evidence-based report contracts.
+- Install missing namespaced launchers for all 20 workflows under `.agents/skills` through explicit `init`.
+- Add `skills list` and `skills show <name>`, including JSON output with paths, descriptions, content, and package version.
+- Load current workflow instructions from the lockfile-pinned package rather than overwriting customized local skills on upgrades.
+- Preserve the original `0.4.0` context block and append a separately marked design/browser-review routing block once.
+- Cover installed-package retrieval, launcher creation, customized skills, malformed markers, symlink preflight, repeated initialization, and offline tarball installation.
+
+## Install or upgrade
+
+```bash
+npm install --save-dev --save-exact ai-design-context@0.5.0
+npx ai-design-context init
+npx ai-design-context skills list
+npx ai-design-context skills show visual-qa
+```
+
+Use the installed launchers or `skills show` to apply the workflow: understand the screen, retrieve research/rules, implement within the existing stack, exercise browser interactions, capture and inspect screenshots, check responsive/accessibility behavior, fix authorized issues, and retest.
+
+## Capability and evidence limits
+
+The package supplies knowledge and agent workflows. Browser tools or the project's Playwright setup, browser binaries, image viewing, and an image-capable model must be supplied by the agent/project environment. Missing capabilities are unverified scope, not a QA pass. One screenshot does not establish responsive, keyboard, virtual-keyboard, screen-reader, or asynchronous-state behavior.
+
+The new skills use existing graph-backed guidance and are not registered knowledge objects. Existing draft/seed research and rules retain their maturity. Skill application scenarios and the reference fixture check validate the workflow's operation; they do not establish a general quality gain or replace paired benchmark evidence.
+
+See [Design and Browser QA](docs/BROWSER_DESIGN_QA.md).

package/SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-AI Design Context ships a local npm CLI, documentation, schemas, a knowledge graph, and validation tools including DesignLint. It does not run a hosted service. Graph retrieval is read-only and offline; `init` explicitly writes agent instructions and missing templates into the current project. Installation has no initialization hooks. Review repository guidance as input to your agent, with project-specific instructions remaining authoritative.
+AI Design Context ships a local npm CLI, documentation, schemas, a knowledge graph, and validation tools including DesignLint. It does not run a hosted service. Graph and skill retrieval are read-only and offline; `init` explicitly writes agent instructions, missing templates, and namespaced `.agents/skills` launchers into the current project. Installation has no initialization hooks. Browser and image tools belong to the consuming agent/project environment. Review repository guidance as input to your agent, with project-specific instructions remaining authoritative.
 
 ## Supported Versions
 

package/docs/AGENT_CONTEXT.md

@@ -14,7 +14,7 @@ npx --no-install ai-design-context context --object PAT-00002 --format json
 
 The installed CLI always reads its own graph, not a `registry/` directory in the consuming project. Markdown lists absolute paths so the agent can open the selected files. JSON preserves the relative graph `path`, adds an `absolutePath` to anchors and objects, and adds the package's `knowledgeRoot` at the top level. These reading paths depend on the installation location and must not be used as stable object identifiers.
 
-`npx ai-design-context init` appends a marked block to `AGENTS.md` and creates only missing starter-kit files. It preserves current project instructions, populated files, and existing marked blocks. It rejects malformed markers, symlinked destinations, and incompatible file/directory destinations before creating templates. Installation itself performs no initialization.
+`npx ai-design-context init` appends marked context and design-review blocks to `AGENTS.md` and creates only missing starter-kit files and namespaced `.agents/skills` launchers. It preserves current project instructions, populated files, customized launchers, and existing marked blocks. It rejects malformed markers, symlinked destinations, and incompatible file/directory destinations before creating files. Installation itself performs no initialization. See [Design and Browser QA](BROWSER_DESIGN_QA.md) for discovery, the `skills` CLI, and browser/image capability requirements.
 
 Retrieval is lexical and read-only. A `--review` query matches a known graph object or phrase; it does not inspect or judge arbitrary files in the product repository. Resolve relevant context, then inspect the implementation separately. See [installation](../starter-kit/INSTALL_WITH_AGENT.md) for pre-publication tarball use.
 

package/docs/BROWSER_DESIGN_QA.md

@@ -0,0 +1,52 @@
+# Design and Browser QA
+
+AI Design Context connects product/design reasoning with evidence-based checks of implemented screens. Version `0.5.0` adapts four user-supplied checklists from `Skills.zip` into executable agent workflows: `design-understand`, `visual-qa`, `responsive-check`, and `accessibility-check`. They complement the existing specialist skills; they do not add new design rules or become registry objects.
+
+## Install and discover
+
+```bash
+npm install --save-dev --save-exact ai-design-context@0.5.0
+npx ai-design-context init
+npx ai-design-context skills list
+npx ai-design-context skills show visual-qa
+```
+
+`init` creates missing namespaced launchers under `.agents/skills/ai-design-context-<name>/SKILL.md` for all 20 bundled skills. It preserves existing launchers and project instructions. Each launcher reads its full workflow from the installed package with `skills show`; upgrading the pinned package updates the workflow without overwriting local customization. `skills list --format json` and `skills show <name> --format json` expose source paths, content, descriptions, and the package version for other tooling.
+
+Codex discovers repository skills in `.agents/skills` and can match their descriptions automatically. If the skill list does not refresh, restart the agent. Other runtimes can load workflows through `skills show` and the `AGENTS.md` routing section; automatic discovery depends on their own supported directories. See [official skill discovery documentation](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills).
+
+For a project already initialized with `0.4.0`, rerun `init` after the npm update. The original context block stays intact; a separately marked design-and-review routing block is appended once, and missing launchers are installed. Edited blocks and existing local skills remain authoritative. Commit the lockfile, chosen templates, `AGENTS.md`, and `.agents/skills` with your project instructions.
+
+## Workflow
+
+| Stage | Workflow | Evidence |
+| --- | --- | --- |
+| Understand | `design-understand` for an existing screen; `product-designer` for new product direction | User goal, primary action, existing objects, source components, assumptions. |
+| Ground | `agent-context` | Retrieved research, rules, and patterns with explicit maturity limits. |
+| Implement | Visual, interaction, mobile, and design-system specialists | Focused changes within the project's existing stack and logic. |
+| Inspect | `visual-qa`, `responsive-check`, `accessibility-check` | Browser interactions, screenshots opened by the model, DOM measurements, keyboard/error recovery observations. |
+| Review | `design-reviewer` | Scoped verdict, severity-ordered findings, graph traceability, retest results, and coverage gaps. |
+
+Use an available browser connector/tool or the project's existing Playwright setup. Open the actual screen, exercise its primary flow, resize supported viewports, scroll, inspect dialogs and sticky regions, and capture relevant states. Use semantic roles and labels when the browser tool supports them. Inspect the resulting image pixels with an image-capable model. Compare a supplied design reference under matching viewport, state, theme, scale, and content.
+
+Example exploratory CSS viewports are 390x844, 768x1024, and 1440x900; use the product's supported targets and affected breakpoints. Viewport emulation does not establish physical touch, virtual-keyboard resizing, safe areas, or screen-reader behavior. Record those as unverified when not actually exercised.
+
+## What the npm package provides
+
+| Capability | Supplied by the package |
+| --- | --- |
+| Knowledge graph and workflow instructions | Yes, versioned and local. |
+| Discoverable repository skill launchers | Yes, after explicit `init`. |
+| Browser connector, Playwright runtime, or browser binaries | No; use tools already available to the agent/project. |
+| Image viewing and model vision | No; the agent's runtime/model must support them. |
+| Screenshot-based compliance certification or universal design-quality guarantee | No. |
+
+If tools are absent, continue with source or supplied-image inspection and label the scope **PARTIAL**. A static screenshot cannot prove responsive interactions, keyboard behavior, asynchronous state handling, or numerical contrast ratios. Missing evidence is a coverage gap rather than a pass or a confirmed product defect.
+
+## Review output
+
+Keep evidence in the project's established location; otherwise use a dated folder under `output/playwright/`. Each confirmed issue records its severity, screen/component, viewport and state, reproducible actions, observed versus expected behavior, applicable graph/reference basis, screenshot/measurement, impact, proposed fix, and retest result. Label unverified component/file attribution as a hypothesis.
+
+Finish with a table of **surface | viewport | state/input | evidence | checked/unverified/not applicable**. Use `PASS`, `NEEDS WORK`, or `PARTIAL` for the declared scope. After an authorized fix, repeat the failed check and relevant neighboring layouts under matching conditions; run the project's code checks. The existing `examples/todo-reference` fixture can exercise this process but is not a new benchmark pair or evidence of general quality gains.
+
+Tool mechanics: [Playwright screenshots](https://playwright.dev/docs/screenshots), [emulation](https://playwright.dev/docs/emulation), and [role/label locators](https://playwright.dev/docs/locators). Upstream guidance remains `CHECK-00001`, applicable registered rules and research, and explicit user constraints.

package/docs/GITHUB_SETUP.md

@@ -6,23 +6,30 @@ The project is named **AI Design Context** and the npm package is `ai-design-con
 
 ## Repository Description
 
-Evidence-driven design context and benchmarks for AI agents building products, not dashboards.
+Evidence-driven design context, reusable agent skills, and browser QA workflows for AI coding agents. Install via npm: ai-design-context.
+
+## About Link
+
+https://www.npmjs.com/package/ai-design-context
 
 ## Suggested Topics
 
 - ai
+- ai-design-context
+- ai-agents
+- agent-skills
 - design
 - ux
 - product-design
-- ai-agents
-- codex
-- cursor
-- design-systems
+- visual-testing
 - accessibility
-- frontend
+- playwright
+- knowledge-graph
+- codex
+- npm
 
 ## Release Positioning
 
-The first public release should present AI Design Context as a schema-first knowledge base with benchmark-backed validation, not as a UI kit, component library, or generic design system.
+The current release packages a schema-first knowledge graph, reusable design skills, and browser/image QA workflows. Browser automation and image-model capabilities must be available in the consuming agent/project; the package itself does not provision them. Reference-fixture and skill smoke checks validate the process, while paired benchmarks remain the source for any comparative quality claim.
 
 Do not claim broad product-quality improvement until benchmark evidence supports it across repeated runs.

package/docs/INDEX.md

@@ -2,6 +2,8 @@
 
 Read these files in order when you are new to AI Design Context or when an agent needs repository context.
 
+For npm installation and the implemented-screen QA loop, see [Design and Browser QA](BROWSER_DESIGN_QA.md), [Agent Context](AGENT_CONTEXT.md), and [npm Releases](NPM_RELEASE.md).
+
 AI Design Context is a connected knowledge graph. Each layer depends on the previous one:
 
 ```text

package/docs/NPM_RELEASE.md

@@ -34,7 +34,7 @@ The workflow uses a GitHub-hosted runner, Node.js 24, npm >=11.5.1, and `id-toke
 
 1. Update `package.json` and `package-lock.json` to a new version, write its changelog, and run `npm run check` and `npm test`.
 2. Commit and push the reviewed source, including the workflow and lockfile.
-3. Create and push a tag matching `v<package.json version>`, such as `v0.4.1`.
+3. Create and push a tag matching `v<package.json version>`, such as `v0.5.1`.
 4. Publish a GitHub Release for that tag. This triggers **Publish npm Package**.
 5. Confirm the workflow succeeds, then verify the version in npm.
 

package/examples/todo-reference/review-evidence/2026-10-06-skills-qa/README.md

@@ -0,0 +1,29 @@
+# Browser QA workflow smoke check
+
+Date: 2026-10-06. Target: the unchanged `examples/todo-reference` fixture, served locally. Purpose: exercise the browser/image workflow documented by the new v0.5.0 skills. This is a smoke check, not a paired benchmark, quality score, accessibility certification, or promotion of graph maturity.
+
+## Scope and reproduction
+
+Open the fixture in Playwright's browser at 390x844 CSS pixels. Capture the default state. Submit the empty capture input, observe the alert `Enter a task before adding it.`, and capture the error state. Fill the input with `Review a long grocery list item and verify that its complete title remains readable on a narrow screen`; press Tab, capture keyboard focus on the submit button, then press Enter and capture the saved list.
+
+Resize the same browser to 1440x900 and capture the list. Open `Pick up fruit for breakfast`, capture desktop details, then resize the open detail surface to 390x844 and capture the mobile layout. All seven resulting images were opened and visually inspected. The fixture's static header date is sample content, not the run date.
+
+## Coverage
+
+| Surface | Viewport | State/input | Evidence | Result |
+| --- | --- | --- | --- | --- |
+| List and capture | 390x844 | Default | `mobile-default.png` | Inspected; primary capture action and list readable. |
+| Capture | 390x844 | Empty submission | `mobile-error.png`, browser alert snapshot | Observed textual error and input focus. |
+| Capture | 390x844 | Fill, Tab | `mobile-keyboard-focus.png`, active-element observation | Visible submit-button focus inspected. |
+| List | 390x844 | Enter to save long title | `mobile-saved.png`, updated browser snapshot | Item inserted; title wraps in list. DOM observation: viewport and document scroll width both 390px. |
+| List | 1440x900 | Saved state | `desktop-default.png` | Inspected; title wraps without visible collision. |
+| Details | 1440x900 | Pointer opens item | `desktop-detail.png`, browser snapshot | Source list remains visible beside details. |
+| Details | 390x844 | Resize open details | `mobile-detail.png` | Inspected mobile detail geometry; not proof of modal focus management. |
+
+No confirmed blocking visual defect was established in the inspected captures. Overall verdict is **PARTIAL** for complete UI QA: tablet/neighboring breakpoints, physical touch, real virtual keyboard, full dialog keyboard cycle, loading timing/layout, retry, reduced motion, numeric contrast, clickable target measurements, and screen-reader behavior were not tested. No supplied design reference existed for layout comparison. The single input's horizontal text scroll is distinct from accidental page overflow.
+
+## Skill behavior and package checks
+
+The four skill documents passed metadata validation. Read-only application scenarios exercised missing browser/image evidence, existing-screen diagnosis, responsive emulation limits, and accessibility limitations. Reports separated observed evidence from unverified states and avoided inventing defects or broad passes. These are scenario checks, not estimates of population-level agent performance.
+
+Automated tests separately verify packed installation, graph/source retrieval, discoverable launcher creation, preservation of local files, marker validation, and symlink preflight. See `tools/cli.test.mjs` and `tools/package.test.mjs`. Grounding uses existing `CHECK-00001` and applicable rules/research; the new skills remain outside the knowledge registry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-design-context",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Evidence-driven design knowledge and context retrieval for AI coding agents.",
   "license": "MIT",
   "author": "Dev Ik",
@@ -42,6 +42,7 @@
     "tools/cli.mjs",
     "tools/context.mjs",
     "tools/init.mjs",
+    "tools/skills.mjs",
     "tools/validate-knowledge.mjs",
     "tools/validate-benchmark-evidence.mjs",
     "tools/designlint.mjs",

package/skills/README.md

@@ -24,6 +24,16 @@ Use skills as an agent design team:
 | `agent-context` | Read-only graph context retrieval for an implementation or review target. |
 | `prompt-architect` | Graph-backed prompt structure and output contracts. |
 | `knowledge-graph-architect` | Schema, registry, generated indexes, relationships, and validation scope. |
+| `design-understand` | Diagnose an existing screen before choosing UI changes. |
+| `visual-qa` | Inspect rendered screenshots and interactions; record defects and evidence coverage. |
+| `responsive-check` | Execute viewport, overflow, wrapping, sticky-region, and mobile-input checks. |
+| `accessibility-check` | Execute semantic, keyboard, dialog, error, target, and reduced-motion checks. |
+
+## Installation and execution
+
+The npm CLI's `init` installs missing namespaced launchers for all 20 skills under `.agents/skills/ai-design-context-<name>/SKILL.md`. Launchers use `npx --no-install ai-design-context skills show <name>` to read the current pinned workflow, so package upgrades do not overwrite customized local skill files. Existing local skills are preserved.
+
+Use `npx ai-design-context skills list` to discover bundled workflows and `skills show visual-qa` to load a specific one. Browser automation and image analysis require tools/model capabilities supplied by the agent or project. See [Design and Browser QA](../docs/BROWSER_DESIGN_QA.md).
 
 ## Routing
 
@@ -46,3 +56,5 @@ Use `prompt-architect` when writing or reviewing agent prompts.
 Use `knowledge-graph-architect` when schemas, registry records, generated indexes, or validation behavior are affected.
 
 Use `design-reviewer` as the final quality gate.
+
+For existing UI, start with `design-understand`. After implementation, use `visual-qa`, `responsive-check`, and `accessibility-check` to collect concrete browser/image evidence, then hand off to `design-reviewer`. Keep unverified states explicit; source inspection alone is not a rendered QA pass.

package/skills/accessibility-check/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: accessibility-check
+description: Use when implemented interactive UI needs practical checks of keyboard navigation, visible focus, accessible names, form labels and errors, dialog focus, touch targets, color-only status, or reduced motion. Skip legal certification and backend-only work.
+---
+
+# Accessibility Check
+
+Exercise the user's flow and inspect semantics as well as pixels. This execution skill complements `accessibility-reviewer`; it is not a conformance certificate.
+
+Retrieve matching graph context and read applicable research, particularly `A11Y-001` through `A11Y-004`. Record the actual browser, viewport, data, states, and tools. If only source or a screenshot is available, identify that limited scope and mark behavioral checks unverified.
+
+## Check the implemented flow
+
+- Inspect semantic elements and accessible names. Buttons perform actions; links navigate. Inputs have associated labels. Icon-only controls have meaningful names or decorative icons are hidden. Prefer native elements; inspect existing custom controls without adding unnecessary ARIA.
+- Use keyboard input to follow the primary journey. Check Tab and Shift+Tab order, visible focus, Enter/Space where relevant, and access to actions that also work with a pointer. For dialogs and sheets, observe initial focus, containment when modal, Escape behavior where supported, and focus restoration after closing. A role locator alone does not establish keyboard behavior.
+- Trigger input errors and recovery. Observe specific textual messages, association with the affected input, retained values, and retry. Check applicable loading, success, and disabled states for understandable feedback and remaining navigation.
+- Measure clickable target bounds, not just visible icons, when applying the graph's `A11Y-001`. Inspect responsive collision risks with `responsive-check`.
+- Inspect focus and status in screenshots. For contrast, use actual foreground/background values and a suitable measurement tool; a visual impression cannot prove a numeric contrast ratio. State the applicable criterion and report unknown composite/translucent colors as unresolved. Status must remain understandable without color alone.
+- When interaction motion exists, exercise the available reduced-motion preference and confirm equivalent function and feedback. Record any assistive-technology testing actually performed; browser DOM/role inspection does not prove screen-reader behavior.
+
+For authorized fixes, preserve business logic, use the existing component system, and repeat the failed keyboard/error/state interaction. Capture focused evidence before and after where visible behavior is involved.
+
+## Output
+
+Return **scoped verdict | tools and conditions | confirmed findings | coverage gaps**. A finding includes severity, affected control/state, keyboard or pointer reproduction, measured/observed evidence, user impact, applicable graph rule or external criterion, fix, verified component/file, and retest status. Distinguish **checked**, **unverified**, and **not applicable** for labels/semantics, keyboard/focus, dialogs, errors/recovery, targets, contrast, reduced motion, and assistive technology. Missing evidence is not a pass or a confirmed implementation defect.
+
+Sources: `CHECK-00001`, `RULE-00009` through `RULE-00013`, `research/accessibility/textual-error-recovery.md`, and `research/accessibility/keyboard-focus-and-interaction-motion.md`. [Playwright role and label locators](https://playwright.dev/docs/locators) provide useful semantic feedback but do not replace accessibility audits.

package/skills/design-understand/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: design-understand
+description: Use when an existing screen, screenshot, or layout must be understood before UI changes, visual polish, or redesign. Skip backend maintenance and greenfield product direction without an existing surface.
+---
+
+# Understand an Existing Screen
+
+Identify what the user is trying to accomplish before choosing visual changes. For a new product without an existing screen, use `product-designer` instead.
+
+1. Record the user's goal, primary action, secondary actions, core objects, and current state. Separate observed behavior from assumptions and questions that affect the change.
+2. Retrieve task context with `npx --no-install ai-design-context context --task "<matching phrase or known slug>" --intent implement`. Read the returned research and rules; use `--platform mobile` for narrow or touch-first screens. Record unresolved knowledge needs instead of inventing rules.
+3. Inspect the actual screen or supplied image with the available browser/image tools. Use source inspection to identify existing components, semantic tokens, and responsive conventions. A screenshot describes one state, not the entire interaction model.
+4. Diagnose hierarchy, layout, typography, spacing, component consistency, and relevant default, loading, empty, error, success, and disabled states. Explain how competition for attention affects the primary task. Distinguish concrete friction from an unsupported preference about product feel.
+5. Propose the smallest changes that serve the stated goal. Keep business logic and the existing stack. New visual directions require user intent and upstream references, not only taste.
+
+## Handoff
+
+Return: **screen and user goal | primary/secondary actions | observed strengths and problems | assumptions and missing states | ranked improvements with graph/reference evidence | affected components/tokens | verification plan**. Rank up to three consequential problems when present; do not invent three defects to fill a quota.
+
+Use `visual-designer` or `interaction-designer` for the selected change, `reference-driven-design` for requested new visual directions, and `visual-qa` after implementation. Preserve the evidence limits of all `draft` and `seed` graph objects.
+
+Graph anchors: `RULE-00001` / `PRD-001` for the primary repeated action, `RULE-00004` / `IA-002` for object structure, `RULE-00008` / `VIS-001` for existing tokens, and `CHECK-00001` for state and review coverage. Their source research remains the basis of design advice.

package/skills/responsive-check/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: responsive-check
+description: Use when a screen must be checked across mobile, tablet, laptop, or desktop sizes for overflow, wrapping, sticky overlaps, collapsed navigation, unreachable actions, sheets, dialogs, tables, filters, or charts. Skip non-UI maintenance.
+---
+
+# Responsive Check
+
+Verify adaptation through browser behavior and inspected screenshots. This execution skill complements `mobile-ux-expert`, which guides touch-first product decisions.
+
+## Scope and preparation
+
+Identify the target devices, primary task, changed breakpoints, long-content cases, and relevant states. Retrieve focused graph context with `--platform mobile` and read the applicable research and rules. Use the project's actual breakpoints and device targets. Example CSS viewports for exploratory sampling are 390x844, 768x1024, and 1440x900; include narrower widths and just below/above affected breakpoints when the product supports them. These samples are not universal layout rules or a substitute for actual devices.
+
+Use available browser tools or the project's existing Playwright setup. Record viewport dimensions, scale, theme, data, and state. If browser access is absent, provide a source/screenshot-limited review and mark unseen widths and interactions unverified.
+
+## Execute
+
+1. Load the same flow at each selected width. Exercise capture/navigation, open and close sheets or dialogs, and scroll through long content and sticky regions.
+2. Check horizontal page overflow, broken grids, long labels and entries, clipped text, navigation collapse, hidden primary actions, oversized dialogs, and controls obscured by sticky elements. For tables/charts, distinguish intentional bounded horizontal scrolling from accidental page overflow.
+3. Observe wrapping and control placement before and after state changes, including loading, validation errors, retry, and success. Compare geometry when `PERF-001` applies.
+4. Inspect images of each captured state and confirm suspected bounds with DOM measurements. Judge touch targets using the clickable area and the graph's `A11Y-001`, not icon dimensions alone.
+5. For mobile input flows, record whether a real virtual keyboard was exercised. Desktop viewport emulation does not prove keyboard resizing, safe-area handling, or physical-device touch behavior. Mark those as gaps if relevant and untested.
+6. After authorized fixes, repeat the failing width, relevant neighboring breakpoint, and affected wide layout. Capture before/after evidence under matching conditions.
+
+## Output
+
+Return a **scoped verdict**, then **viewport | state/action | observed behavior | screenshot/measurement | checked/unverified/not applicable**. Each confirmed issue includes severity, reproduction, user impact, graph/reference basis, focused fix, and verified component/file when known. Report breakpoint behavior and physical-device gaps separately. A screenshot at one size is not a responsive pass.
+
+Sources: `CHECK-00001`, `RULE-00005` / `UX-001`, `RULE-00009` / `A11Y-001`, `RULE-00011` / `PERF-001`, and their retrieved source research. Use [Playwright emulation](https://playwright.dev/docs/emulation) for tool mechanics; it does not replace device evidence.

package/skills/visual-qa/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: visual-qa
+description: Use when an implemented screen, screenshot, or UI change needs visual QA for spacing, alignment, wrapping, clipping, overlap, hierarchy, component states, or comparison with a supplied design reference. Skip backend-only changes.
+---
+
+# Visual QA
+
+Review observed UI against the user's task, existing design system, and retrieved graph context. This execution skill complements `design-reviewer`, which owns the final traceability review.
+
+## Inputs and capabilities
+
+Identify the screen, primary action, changed components, relevant states, target devices, and any supplied reference. Retrieve focused context with `npx --no-install ai-design-context context --review "<graph ID or matching phrase>" --intent qa`; read the returned research and rules. An arbitrary application path is not automatically a graph match.
+
+Record which tools are actually available:
+
+- A browser tool or the project's existing Playwright setup for navigation, viewport changes, clicks, keyboard input, scrolling, DOM measurements, and screenshots.
+- An image-viewing tool and an image-capable model for inspecting captured pixels and references.
+- Source and DOM inspection for relating a visible issue to its implementation.
+
+If a capability is unavailable, continue with the available evidence and mark the missing checks **unverified**. Skills do not install browser binaries, provision model vision, or enable MCP tools. A code-only review cannot establish rendered quality; a screenshot cannot establish keyboard or responsive behavior.
+
+## Browser and image loop
+
+1. Open the actual implementation. Record its URL or fixture path, browser, viewport in CSS pixels, theme, zoom, data, and state. Exercise the primary action and relevant default, loading, empty, error, success, and disabled states; mark inapplicable states with a reason.
+2. Check narrow and wide layouts with `responsive-check`. Open and close menus, dialogs, and sheets, scroll past sticky regions, and exercise keyboard focus with `accessibility-check`.
+3. Save viewport screenshots for geometry and separate full-page screenshots for long content. Use the project's evidence convention; otherwise create a dated review folder under `output/playwright/`. Record the steps that reproduce each capture.
+4. Open the captured images, not just their filenames. Inspect alignment, spacing consistency, typography, line breaks, clipped text, collisions, icon alignment, button/input sizing, content density, primary-action prominence, and state feedback. Confirm suspected geometry problems with DOM measurements where possible.
+5. If a design reference exists, compare matching viewport, state, theme, content, and scale. Record unmatched conditions instead of attributing every pixel difference to a defect. Without a reference, assess task clarity and existing tokens; do not invent a target composition from taste.
+6. For authorized fixes, make a focused patch, repeat the failed interaction, and recapture the same conditions. Run the project's relevant code checks. Preserve product logic and the existing UI stack.
+
+## Report contract
+
+Lead with **PASS**, **NEEDS WORK**, or **PARTIAL**, scoped to the surfaces and states actually reviewed. PARTIAL means missing evidence prevents completing that scope. Separate observed defects from coverage gaps; a skipped check is not a confirmed product defect.
+
+For each finding, include:
+
+| Field | Required evidence |
+| --- | --- |
+| ID and severity | Stable review-local ID; Critical, Major, Minor, or Polish based on impact on the primary task. |
+| Surface and conditions | Screen/component, viewport, data/state, and input method. |
+| Reproduction | Actions another reviewer can repeat. |
+| Observed / expected | What happened; applicable rule, pattern, reference, or explicit knowledge gap. |
+| Evidence | Screenshot path and inspected region; DOM measurement or interaction observation when available. |
+| Impact and fix | User consequence, focused correction, likely file/component when verified. |
+| Retest | Outcome and matching after-capture, or pending. |
+
+Finish with a coverage table: **surface | viewport | state/input | evidence | checked/unverified/not applicable**. List missing tools and any reference-comparison gaps. Do not infer a global pass from one desktop screenshot.
+
+## Graph anchors and tool references
+
+- `CHECK-00001` / `checklists/DESIGN_QA.md`: state, responsive, accessibility, and evidence boundaries.
+- `RULE-00008` / `VIS-001`: existing semantic tokens.
+- `RULE-00014` / `VIS-002`: content and primary-action hierarchy.
+- `RULE-00011` / `PERF-001`: loading-state layout stability.
+- [Playwright screenshots](https://playwright.dev/docs/screenshots) and [emulation](https://playwright.dev/docs/emulation) describe capture and viewport capabilities, not proof that those tools are installed.

package/starter-kit/INSTALL_WITH_AGENT.md

@@ -20,7 +20,7 @@ After setup, the product repository has:
 
 ## npm Installation
 
-The package is implemented in this checkout; registry installation requires its first npm publication. After publication, run these commands from the product repository:
+The package is published on npm. Run these commands from the product repository:
 
 ```bash
 npm install --save-dev --save-exact ai-design-context
@@ -28,9 +28,11 @@ npx ai-design-context init
 npx ai-design-context context --task quick-capture --platform mobile --intent implement
 ```
 
-Before publication, run `npm pack` in the knowledge-source checkout, then install that generated `.tgz` with `npm install --save-dev /path/to/ai-design-context-0.4.0.tgz` in the product repository. The same `init` and `context` commands work with the local tarball.
+For local evaluation before a new version is published, run `npm pack` in the knowledge-source checkout, then install that generated `.tgz` with `npm install --save-dev /path/to/ai-design-context-0.5.0.tgz` in the product repository. The same `init`, `context`, and `skills` commands work with the local tarball.
 
-`init` appends an optional, marked section to the existing `AGENTS.md` and creates only missing files under `docs/`, `templates/`, `reviews/`, and `benchmarks/`. It preserves existing project-specific instructions, populated documents, and edited integration blocks. Repeat it safely to create newly missing templates; it does not refresh an existing block. Review any newly created placeholders and fill them with actual product context. There are no install hooks and no runtime dependencies.
+`init` appends optional, marked context and design-review sections to the existing `AGENTS.md` and creates only missing files under `docs/`, `templates/`, `reviews/`, `benchmarks/`, and `.agents/skills/`. It preserves existing project-specific instructions, populated documents, edited integration blocks, and customized skill launchers. Repeat it safely to create newly missing templates or launchers; it does not refresh an existing block. An upgrade from `0.4.0` adds the new skill-routing section without changing the original block. Review any newly created placeholders and fill them with actual product context. There are no install hooks and no runtime dependencies.
+
+The 20 namespaced launchers read current workflows from the pinned package. Use `npx ai-design-context skills list` and `npx ai-design-context skills show visual-qa`. Browser and image tools must be available in the agent/project; missing capabilities are recorded as unverified QA scope. See [Design and Browser QA](../docs/BROWSER_DESIGN_QA.md).
 
 Ask the agent to use the returned absolute reading paths, read research and rules, and preserve evidence limits. JSON output includes `knowledgeRoot`, relative `path`, and `absolutePath`. `--review` matches graph identifiers or phrases rather than analyzing arbitrary product files.
 

package/starter-kit/README.md

@@ -27,6 +27,8 @@ research -> rules -> patterns -> prompts -> prototype -> review -> code -> bench
 
 For an existing repository, start with `INSTALL_WITH_AGENT.md`. It tells an agent how to preserve current instructions and populated project documents.
 
+The npm CLI's `init` also creates missing namespaced `.agents/skills` launchers and a separately marked design/browser-review section. Use `skills list` and `skills show <name>` to load current workflows from the pinned package. Browser tools and image analysis remain capabilities of the agent/project environment.
+
 1. Fill `docs/PRD.md`.
 2. Define users in `docs/PERSONAS.md`.
 3. Map the core journey in `docs/USER_FLOWS.md`.

package/tools/cli.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runContext } from './context.mjs';
 import { initProject } from './init.mjs';
+import { runSkills } from './skills.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const usage = `AI Design Context
@@ -13,9 +14,11 @@ Usage:
   ai-design-context context --task <query> [--platform mobile] [--intent implement] [--format json]
   ai-design-context context --review <object-id-or-phrase> [--intent qa]
   ai-design-context context --object <object-id-or-slug>
+  ai-design-context skills list [--format json]
+  ai-design-context skills show <name> [--format json]
   ai-design-context --version
 
-init appends agent instructions and creates only missing starter-kit templates.
+init appends agent instructions and creates only missing templates and skill launchers.
 context reads the knowledge graph shipped with this installed package.
 Requires Node.js 20 or later. See context --help for all retrieval options.`;
 
@@ -28,14 +31,18 @@ try {
     console.log(version);
   } else if (command === 'context') {
     runContext(args, { root: packageRoot, readingPaths: true, command: 'ai-design-context context' });
+  } else if (command === 'skills') {
+    runSkills(args, packageRoot);
   } else if (command === 'init') {
     if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
-      console.log('Usage: ai-design-context init\nAppend agent instructions and create only missing product templates in the current directory.');
+      console.log('Usage: ai-design-context init\nAppend agent instructions and create only missing product templates and namespaced .agents/skills launchers in the current directory.');
     } else {
       if (args.length > 0) throw new Error(`Unknown init argument: ${args[0]}`);
       const result = initProject(process.cwd(), packageRoot);
       console.log(result.instructionsAdded ? 'Added AI Design Context instructions to AGENTS.md.' : 'AI Design Context instructions already present; preserved the existing block.');
       console.log(result.created.length ? `Created: ${result.created.join(', ')}` : 'No missing templates; existing files preserved.');
+      if (result.routingAdded) console.log('Added design and browser review skill routing.');
+      console.log(`Installed ${result.skillsInstalled.length} missing skill launcher(s); existing skills preserved.`);
     }
   } else {
     throw new Error(`Unknown command or argument: ${command}\n${usage}`);

package/tools/init.mjs

@@ -1,8 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { skillCatalog, skillLauncher } from './skills.mjs';
 
 const startMarker = '<!-- ai-design-context:start -->';
 const endMarker = '<!-- ai-design-context:end -->';
+const skillsStartMarker = '<!-- ai-design-context:skills:start -->';
+const skillsEndMarker = '<!-- ai-design-context:skills:end -->';
 const templates = [
   'docs/PRD.md',
   'docs/PERSONAS.md',
@@ -40,6 +43,27 @@ Treat \`draft\` and \`seed\` guidance as bounded evidence. Matching is lexical,
 Use existing product documentation first. Fill any newly created starter-kit placeholders with actual product context; use \`reviews/DESIGN_REVIEW.md\` for UI review.
 ${endMarker}`;
 
+const routingInstructions = `${skillsStartMarker}
+## Design and browser review skills
+
+AI Design Context installs namespaced workflow launchers under \`.agents/skills/\`. Start with \`ai-design-context-design-understand\` for an existing screen and \`ai-design-context-product-designer\` for product direction. Use visual, interaction, and design-system specialists for implementation within the existing stack.
+
+After UI changes, use \`ai-design-context-visual-qa\`, \`ai-design-context-responsive-check\`, and \`ai-design-context-accessibility-check\`, then \`ai-design-context-design-reviewer\` for the final evidence and traceability review. Open the real UI with available browser tools or the project's Playwright setup, exercise the primary flow and relevant states, capture screenshots, inspect them with an image-capable model, make authorized fixes, and repeat the failed checks.
+
+Use \`npx --no-install ai-design-context skills list\` and \`npx --no-install ai-design-context skills show <name>\` to load workflows from the installed package, including in agents without automatic local-skill discovery. Package upgrades refresh these source workflows without replacing customized launchers.
+
+Report viewport, state, reproduction steps, screenshot paths, applicable graph rules, observed defects, and coverage gaps. A source-only review or single screenshot cannot establish complete visual, responsive, or keyboard QA. Missing browser or image tools must be reported as unverified checks, not passes. The package does not provision those tools or change the project's application dependencies.
+${skillsEndMarker}`;
+
+function hasValidBlock(content, start, end) {
+  const starts = content.split(start).length - 1;
+  const ends = content.split(end).length - 1;
+  if (starts !== ends || starts > 1 || (starts === 1 && content.indexOf(start) > content.indexOf(end))) {
+    throw new Error('Invalid AI Design Context markers in AGENTS.md; repair the marked block before running init.');
+  }
+  return starts === 1;
+}
+
 function inspectTarget(root, relativePath) {
   const parts = relativePath.split('/');
   let current = root;
@@ -66,15 +90,15 @@ export function initProject(projectRoot, packageRoot) {
   const agentsPath = path.join(root, 'AGENTS.md');
   const agentsExists = inspectTarget(root, 'AGENTS.md');
   const original = agentsExists ? fs.readFileSync(agentsPath, 'utf8') : '';
-  const starts = original.split(startMarker).length - 1;
-  const ends = original.split(endMarker).length - 1;
-  if (starts !== ends || starts > 1 || (starts === 1 && original.indexOf(startMarker) > original.indexOf(endMarker))) {
-    throw new Error('Invalid AI Design Context markers in AGENTS.md; repair the marked block before running init.');
-  }
+  const hasInstructions = hasValidBlock(original, startMarker, endMarker);
+  const hasRouting = hasValidBlock(original, skillsStartMarker, skillsEndMarker);
 
   // Preflight all destinations and sources before writing any project files.
   const missing = templates.filter((file) => !inspectTarget(root, file));
   const contents = missing.map((file) => [file, fs.readFileSync(path.join(packageRoot, 'starter-kit', file))]);
+  const skillFiles = skillCatalog(packageRoot).map((skill) => ({ skill, file: `.agents/skills/${skill.installedName}/SKILL.md` }));
+  const missingSkills = skillFiles.filter(({ file }) => !inspectTarget(root, file));
+  contents.push(...missingSkills.map(({ skill, file }) => [file, skillLauncher(skill)]));
   const created = [];
   for (const [file, content] of contents) {
     const target = path.join(root, file);
@@ -83,9 +107,10 @@ export function initProject(projectRoot, packageRoot) {
     created.push(file);
   }
 
-  if (starts === 0) {
+  const blocks = [!hasInstructions && instructions, !hasRouting && routingInstructions].filter(Boolean);
+  if (blocks.length > 0) {
     const newline = original.includes('\r\n') ? '\r\n' : '\n';
-    const block = instructions.replaceAll('\n', newline);
+    const block = blocks.join('\n\n').replaceAll('\n', newline);
     if (agentsExists) {
       const separator = original.endsWith(newline) ? newline : `${newline}${newline}`;
       fs.appendFileSync(agentsPath, `${separator}${block}${newline}`);
@@ -95,5 +120,5 @@ export function initProject(projectRoot, packageRoot) {
     }
   }
 
-  return { created, instructionsAdded: starts === 0 };
+  return { created, instructionsAdded: !hasInstructions, routingAdded: !hasRouting, skillsInstalled: missingSkills.map(({ skill }) => skill.installedName) };
 }

package/tools/skills.mjs

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function skillCatalog(root) {
+  const directory = path.join(root, 'skills');
+  return fs.readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((entry) => {
+      const relativePath = `skills/${entry.name}/SKILL.md`;
+      const absolutePath = path.join(root, relativePath);
+      const content = fs.readFileSync(absolutePath, 'utf8');
+      const frontMatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+      const name = frontMatter?.match(/^name:\s*(.+)$/m)?.[1].trim();
+      const rawDescription = frontMatter?.match(/^description:\s*(.+)$/m)?.[1].trim();
+      const description = rawDescription?.replace(/^(["'])(.*)\1$/, '$2');
+      if (name !== entry.name || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || !description) {
+        throw new Error(`Invalid skill metadata: ${relativePath}`);
+      }
+      return { name, installedName: `ai-design-context-${name}`, description, path: relativePath, absolutePath, content };
+    });
+}
+
+export function skillLauncher(skill) {
+  return `---
+name: ${skill.installedName}
+description: ${JSON.stringify(skill.description)}
+---
+
+# AI Design Context: ${skill.name}
+
+Load the current workflow from the project's installed, lockfile-pinned package:
+
+\`\`\`bash
+npx --no-install ai-design-context skills show ${skill.name}
+\`\`\`
+
+Read and apply the returned workflow before acting. Its source location and knowledge root identify where supporting files live. In a product repository, use \`npx --no-install ai-design-context context\` in place of checkout-only \`npm run context --\` examples. Resolve focused graph context and read applicable research and rules before making design decisions.
+
+Preserve existing project instructions and user scope. Use available browser and image tools for rendered checks; record unavailable capabilities and unverified states. This launcher installs instructions, not browser binaries or model vision. Other bundled workflows can be read with \`npx --no-install ai-design-context skills list\` and \`skills show <name>\`.
+`;
+}
+
+export function runSkills(argv, root) {
+  const usage = 'Usage: ai-design-context skills list [--format json]\n       ai-design-context skills show <name> [--format json]';
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) {
+    console.log(usage);
+    return;
+  }
+  const args = [...argv];
+  const formatIndex = args.indexOf('--format');
+  let format = 'markdown';
+  if (formatIndex >= 0) {
+    format = args[formatIndex + 1];
+    args.splice(formatIndex, 2);
+  }
+  if (!['markdown', 'json'].includes(format)) throw new Error('--format must be markdown or json');
+  const [action = 'list', name] = args;
+  if ((action === 'list' && args.length > 1) || (action === 'show' && args.length !== 2) || !['list', 'show'].includes(action)) {
+    throw new Error(usage);
+  }
+  const skills = skillCatalog(root);
+  const { version } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  const common = { version, knowledgeRoot: root };
+  if (action === 'show') {
+    const skill = skills.find((entry) => entry.name === name);
+    if (!skill) throw new Error(`Unknown skill: ${name}`);
+    console.log(format === 'json' ? JSON.stringify({ ...common, ...skill }, null, 2)
+      : `Source: ${skill.absolutePath}\nKnowledge root: ${root}\nPackage version: ${version}\n\nIn product repositories, use npx --no-install ai-design-context context for graph retrieval. Resolve paths in this workflow relative to the knowledge root or its source directory.\n\n${skill.content}`);
+  } else {
+    const entries = skills.map(({ content, ...skill }) => skill);
+    console.log(format === 'json' ? JSON.stringify({ ...common, skills: entries }, null, 2)
+      : `# AI Design Context Skills (${version})\n\n${entries.map((skill) => `- ${skill.name}: ${skill.description}\n  Source: ${skill.absolutePath}\n  Installed launcher: ${skill.installedName}`).join('\n')}`);
+  }
+}