Agent Workspace

English | 中文

This repository is a personal agent workspace for shared AI-agent instructions and reusable agent resources. It maintains a curated set of agent resources under resources/, currently of two types:

• resources/skills/ — agent skills (vendored from upstream or authored in-repo).
• resources/agent-instructions/agent-collaboration/AGENTS.md — the shared, cross-project agent collaboration guidelines (language policy, output principles, git conventions, browser tool selection, etc.).

External resources are vendored — the local copy is the source of truth, and tooling under scripts/vendor/ tracks upstream drift and proposes sync PRs. The root AGENTS.md only contains this repository's project-specific guidance (review rubric for vendor-sync PRs and vendor tooling reference).

The full architecture is documented in agent-resources-vendor-sync-architecture.md.

Directory Structure

agents/
├── .agent-vendor/
│   ├── registry.json           # declared resources (managed by `pnpm agents add`)
│   └── lock.json               # sync state (script-generated)
├── .github/
│   └── workflows/
│       └── vendor-sync.yml     # daily upstream-drift check + PR
├── .gitignore
├── AGENTS.md                   # repository-specific review rubric + vendor tooling reference
├── README.md
├── README.zh-CN.md
├── agent-resources-vendor-sync-architecture.md
├── docs/
├── package.json
├── pnpm-lock.yaml
├── resources/
│   ├── agent-instructions/
│   └── skills/
├── scripts/
│   ├── agents/
│   └── vendor/
└── tsconfig.json

Resource Catalog

Skills (type=skill)

Skill	Origin	Upstream	Use When
chrome-devtools-cli	external	ChromeDevTools/chrome-devtools-mcp	DevTools-level diagnostics: console, network, performance, Lighthouse, memory, extension debugging.
chrome-extension-release	internal	—	Preparing, auditing, packaging, or submitting Chrome extensions.
codex-review	internal	—	Delegating a code review to the locally-installed Codex CLI with a sealed read-only sandbox.
docs-management	internal	—	Structured project documentation with docs/work/, specs, ADRs, progress logs, review notes.
figma-chrome-devtools-visual-qa	internal	—	Comparing Figma designs against live implementations using Figma MCP + chrome-devtools-cli.
figma-plugin-release	internal	—	Figma plugin release workflow with changelog assets, GitHub Actions artifacts, tags, draft releases.
find-skills	external	vercel-labs/skills	Discovering or installing agent skills.
perf-audit	internal	—	Auditing performance, memory, caching, background loading, and runtime cost.
playwright-cli	external	microsoft/playwright-cli	Repeatable browser automation, regression checks, Playwright tests, persistent profiles, extension debugging.
security-audit	internal	—	Project-wide security risk audit with community-trust scoring and context-aware analysis.
surge	internal	—	Operating and troubleshooting Surge via surge-cli: command discovery, runtime diagnostics, state inspection, and environment mutation.

Agent Instructions (type=agent-instruction)

Resource	Origin	Upstream	Use When
agent-collaboration	internal	—	Cross-project agent collaboration guidelines.

How to use

Run pnpm agents --help for the command overview, or pnpm agents add --help / pnpm agents verify --help for subcommand-specific behavior and options.

Add internal resources

Use pnpm agents add for both existing local resource directories and resources you create manually under resources/. Local sources are registered with origin: internal and do not write upstream metadata.

pnpm agents add ./path/to/my-skill --type skill --name my-skill --yes
pnpm agents add ./resources/skills/my-skill --type skill --yes
pnpm agents add ./path/to/team-guidelines --type agent-instruction --name team-guidelines --yes

For skill, the selected directory must contain SKILL.md. For agent-instruction, the selected directory must contain AGENTS.md.

Local paths must be explicit: use ./foo, ../foo, an absolute path, ., or ... Bare owner/repo and owner/repo/path are parsed as GitHub shorthand; if that text also names an existing local directory, the CLI stops with a ./... hint instead of guessing.

Add external resources

Remote sources are copied into resources/<type>/<name>/, registered with origin: external, and locked to the observed upstream tree hash.

pnpm agents add vercel-labs/skills --type skill --list
pnpm agents add owner/repo --type skill --resource my-skill --name my-skill --yes
pnpm agents add owner/repo --type skill --resource skill-one --resource skill-two --yes
pnpm agents add owner/repo --type skill --all --yes
pnpm agents add https://github.com/owner/repo/tree/main/skills/foo --type skill --name foo --yes
pnpm agents add https://gitlab.com/group/repo/-/tree/main/skills/foo --type skill --name foo --yes

If a source contains multiple skill resources, inspect candidates with --list, then select one or more with repeated --resource <name> or add every discovered skill with --all. Running add without an explicit selector fails before writing files. Batch add currently supports only --type skill; agent-instruction remains a single-resource add flow. --name only renames a single selected resource and cannot be used for batch add. Use --ref <branch-or-tag> or a #ref URL fragment when the source is not on main.

Before writing a new resource, agents add verifies the current registry and filesystem. Unrelated orphan resource directories must be resolved first; the only tolerated pre-existing orphan is the canonical directory being registered by that command.

Add command reference

--type is required and must be skill or agent-instruction.

--resource selects a candidate by directory basename, frontmatter name, or kebab-normalized name. Repeat it to add multiple skills in one command.

--all adds every discovered skill from the source. It cannot be combined with --resource or --name.

--name sets the registry name and target directory for a single selected resource. If omitted, skills prefer SKILL.md frontmatter name, then the selected directory basename; remote root agent-instruction resources use the upstream repo name instead of the temporary clone directory. Spaces and underscores are normalized to hyphens; names must be valid kebab-case after normalization.

--yes skips the confirmation prompt. In an interactive terminal, agents add asks for confirmation before copying/registering unless --yes is passed. In non-interactive runs, it proceeds without prompting.

Update existing resources

For internal resources, edit files directly under resources/<type>/<name>/. The registry entry normally stays unchanged; only update .agent-vendor/registry.json through tooling or schema-maintenance work if you rename or move the resource. After editing, refresh validation and lock metadata:

pnpm agents verify
pnpm vendor:refresh-lock

Internal resources have no upstream baseline. vendor:refresh-lock records the new local content hash and keeps the entry in_sync.

External resources are vendored copies, so local edits are supported as repository-local patches. After editing an external resource, run:

pnpm agents verify
pnpm vendor:check

When the local hash differs from the last synced upstream hash, vendor:check writes status: locally_modified, reports the resource as drift-only, and skips the upstream lookup for that resource. GitHub Actions will not open a sync PR while the resource remains locally modified.

To explicitly inspect a locally modified external resource against current upstream, run:

pnpm vendor:compare <name>

vendor:compare is read-only. It fetches current upstream even for locally_modified resources and reports local vs last-synced, upstream vs last-synced, and local vs upstream state. Upstream comparison in the automatic check path resumes after the local copy is restored to the last synced content or after an intentional pnpm vendor:sync <name> replaces the local copy with the current upstream subtree.

Verify

pnpm agents verify

This checks that .agent-vendor/registry.json matches the filesystem and that every registered resource is valid.

Maintenance tooling

Command	Purpose
pnpm agents add ...	Add and register an internal or external resource.
pnpm agents verify	Check registry ↔ filesystem consistency.
pnpm agents:test	Run the agent workspace CLI regression tests used by CI.
pnpm vendor:verify	Internal equivalent used by CI.
pnpm vendor:refresh-lock	Recompute local and upstream content hashes; write lock.json.
pnpm vendor:check	Detect local external drift first; compare upstream only for non-drifted external resources.
pnpm vendor:compare <name>	Read-only comparison for one external resource, including locally modified resources.
pnpm vendor:sync <name>	Replace localPath with the current upstream subtree and update the lock entry.

.github/workflows/vendor-sync.yml runs vendor:check daily (and on demand); for each upstream-updated external resource that is not locally modified it opens one PR (chore/vendor/sync/<name>, label vendor-sync). Reviewers follow the rubric in AGENTS.md → Review guidelines / Vendored resource sync PRs.

Notes

• origin means where the resource is maintained: internal for this repository, external for vendored upstream copies.
• scope and installStrategy are schema defaults for future expansion; V1 resources use scope: project and installStrategy: copy.
• Manual edits to .agent-vendor/registry.json are for schema/tooling maintenance only. Normal add flows should use pnpm agents add.
• Don't hand-edit .agent-vendor/lock.json — it's overwritten by vendor:refresh-lock and vendor:sync.