Agent Workspace

English | 中文

A personal workspace for curating AI-agent resources: skills, agent instructions, and hooks. The registry is the source of truth; vendored external resources live locally under resources/ and are checked for upstream drift by pnpm agents.

Full design: docs/specs/vendor-sync-architecture.md

Quick Start

pnpm agents --help
pnpm agents add owner/repo --type skill --list
pnpm agents add owner/repo --type skill --resource foo --yes
pnpm agents prepare
pnpm agents verify

Every add command must include --type so the CLI can validate the resource shape before it reads or writes files.

Use docs/reference/agents-cli.md for the full CLI reference: source formats, options, examples, exit codes, and side effects.

Resource Catalog

All resources are declared in .agent-vendor/registry.json. Keep this table aligned with the registry.

Resource	Type	Origin	Client	Purpose
chrome-devtools-cli	skill	external	-	DevTools diagnostics and browser automation.
chrome-extension-release	skill	internal	-	Chrome extension release prep.
claude-code-review	skill	internal	codex	Isolated Claude Code CLI code review.
codex-cli-review	skill	internal	claude-code	Isolated Codex CLI code review.
docs-management	skill	internal	-	Structured project docs workflow.
figma-chrome-devtools-visual-qa	skill	internal	-	Figma-to-browser visual QA.
figma-plugin-release	skill	internal	-	Figma plugin release workflow.
find-skills	skill	external	-	Discover or install skills.
github-actions-docs	skill	external	-	GitHub Actions docs-grounded help.
perf-audit	skill	internal	-	Performance and runtime cost audits.
playwright-cli	skill	external	-	Repeatable Playwright automation.
security-audit	skill	internal	-	Project security review.
surge	skill	internal	-	Surge CLI operation and troubleshooting.
agent-collaboration	agent-instruction	internal	-	Shared agent collaboration rules.
codex-docs-context-guard	hook	internal	codex	Codex Stop hook for docs closeout.

Core Concepts

Resource type

• skill: reusable instructions in a directory with SKILL.md.
• agent-instruction: shared collaboration guidance in a directory with AGENTS.md.
• hook: installable hook resources with README.md plus config.toml or hooks/.

Origin

• internal: authored and maintained in this repository.
• external: vendored from an upstream repo. The local copy is authoritative; upstream is only a tracked reference.

Clients

clients is optional metadata for resources that depend on a specific agent client. Current values are codex, claude-code, and generic.

• Omit clients for broadly reusable resources.
• Use a specific client, such as codex, for resources tied to client behavior or directories.
• Use generic only when a resource is intentionally client-neutral; it cannot be combined with specific clients.
• Client definitions live in scripts/vendor/constants.ts. Add new client values there, then run pnpm agents verify, pnpm agents:test, and pnpm exec tsc --noEmit.
• If registry metadata uses an unsupported client, pnpm agents prepare and pnpm agents verify point back to scripts/vendor/constants.ts.

Lock status

External resources use lock statuses to make upstream drift explicit: in_sync, upstream_updated, locally_modified, upstream_deleted, archived, and unknown. See the architecture spec for state-machine details.

Common Workflows

Add a resource

pnpm agents add ./resources/skills/my-skill --type skill --yes
pnpm agents add owner/repo --type skill --resource foo --yes
pnpm agents add ./path/to/codex-hook --type hook --client codex --yes

Edit a resource

pnpm agents prepare
pnpm agents verify

prepare refreshes local lock metadata after resource edits. verify is read-only and is also used by CI.

Check or sync external resources

pnpm agents check
pnpm agents compare <name>
pnpm agents sync <name>

check writes upstream status to lock.json. compare is read-only. sync overwrites the local resource directory with the current upstream subtree.

Archive or delete a resource

There is no remove or archive subcommand yet.

• Archive an external resource by adding archived: true to its registry entry, then run pnpm agents prepare.
• Delete a resource manually by removing its registry entry and localPath, then run pnpm agents prepare.
• Upstream deletion never deletes local files automatically; decide whether to preserve, archive, or replace the local copy.

GitHub Automation

Pull request CI

.github/workflows/ci.yml runs on pull requests and manual dispatch. It installs dependencies from pnpm-lock.yaml, then runs pnpm agents verify, pnpm exec tsc --noEmit, and pnpm agents:test.

Daily vendor sync

.github/workflows/vendor-sync.yml runs daily at 01:06 in Asia/Shanghai (Beijing Time) and can also be started manually. The check job verifies resource metadata, runs pnpm agents check, and keeps the token read-only. When an external resource has an upstream update and is not locally modified, the sync job opens one PR per resource on chore/vendor/sync/<name> with the vendor-sync label.

The workflow skips resources that already have an open sync PR and never auto-merges. It also does not assign reviewers or run an automated review agent. A maintainer or active agent reviews the PR diff and generated body using the rubric in AGENTS.md.

Repository Layout

agents/
├── .agent-vendor/              # registry + generated lock state
├── .github/workflows/          # CI + vendor-sync automation
├── docs/                       # reference docs, specs, work notes
├── resources/                  # skills, agent instructions, hooks
├── scripts/                    # pnpm agents CLI + vendor helpers
├── AGENTS.md                   # repository-specific agent guidance
├── README.md
└── README.zh-CN.md

Documentation

Document	Use for
docs/reference/agents-cli.md	Full pnpm agents CLI reference.
docs/specs/vendor-sync-architecture.md	Data model, lock state machine, sync behavior, extension points.
AGENTS.md	Repository-specific review rubric and vendor tooling notes.
docs/README.md	Documentation index.