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

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.

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

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.

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.

Ignored, untracked files inside resource directories must be removed, moved, or tracked with git add -f before refreshing lock metadata. Ignored Markdown Translate outputs named *_<language>_mdt.md are excluded from local tree hashes and do not block prepare or verify; matching files that are not ignored still fail locally.

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.

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 sync job uses a repository-installed GitHub App token for PR branch pushes and PR creation. Configure VENDOR_SYNC_APP_CLIENT_ID as a repository variable and VENDOR_SYNC_APP_PRIVATE_KEY as a repository secret before relying on automated PR creation.

The workflow skips resources that already have an open sync PR and never auto-merges. It also does not run an automated AI review. After a vendor-sync PR is created, a maintainer can manually ask an agent to review the PR diff and generated body using the AGENTS.md rubric.

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