From 73bf26f5e292e7c8658b68e6ebb7c842b60a2f50 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Wed, 26 Aug 2026 15:34:25 +0800 Subject: [PATCH] docs(agents): streamline global guidance Signed-off-by: Ryan Yin --- agents/AGENTS.md | 166 +++++++++++++++++++-------------------- agents/install-skills.md | 65 +++++++++------ 2 files changed, 124 insertions(+), 107 deletions(-) diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 0dfd2d12..be6ab0da 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -1,110 +1,108 @@ -# Personal Global Agent Rules +# Personal global agent rules -This file defines my global defaults and safety boundaries for coding agents. +These rules define my default safety boundaries and working preferences for coding agents. -## 1) Instruction Priority +## Scope and precedence Apply instructions in this order: -1. Runtime system/developer instructions -2. User task request -3. Project-local policy (`AGENTS.md`, `CLAUDE.md`, repo docs) -4. These global rules +1. Runtime system and developer instructions +2. The current user request +3. Safety and secret-handling rules in this file +4. Project-local policy (`AGENTS.md`, `CLAUDE.md`, and repository documentation) +5. Other defaults in this file -If rules conflict, follow the higher-priority source and state the conflict briefly. +Project-local policy may override global defaults but must not weaken safety or secret handling. +Follow the higher-priority source when rules conflict and state the conflict briefly. -## 2) Hard Safety Boundaries (MUST NOT) +## Safety and authorization -- MUST NOT read/write outside the approved workspace. -- MUST NOT perform broad operations on the entire home directory. -- MUST NOT mutate remote Git state unless explicitly requested. - - Examples: `git push`, creating/updating remote PRs/Issues via `gh`. -- MUST NOT auto-run remote-mutating commands unless explicitly requested. - - Examples: `kubectl apply/delete`, `helm upgrade`, `terraform apply`, remote `ssh` mutation. -- MUST NOT perform destructive or irreversible operations, or use force options (e.g. `rm -rf`, - `terraform destroy`). -- MAY perform explicitly requested, verified, and recoverable cleanup (e.g. `git branch -d` for a - fully merged branch). -- MUST NOT expose or commit secrets (tokens, keys, kubeconfig credentials, passwords). +### Workspace access -## 3) Security and Secrets Handling +- Access only runtime-approved roots and paths explicitly placed in scope. +- Do not perform broad operations on the entire home directory. -- Never write secret literals into tracked files. -- Use environment variables, secret managers, or placeholders. -- Redact sensitive output in logs and summaries. -- For infra/IaC changes, prefer plan/eval/check before apply/deploy. +### Remote changes -### Secret Access +- Do not mutate remote state unless the user explicitly requests it. +- Remote mutations include `git push`, creating or updating remote PRs and Issues via `gh`, + `kubectl apply/delete`, `helm upgrade`, `terraform apply`, and remote `ssh` changes. +- For infrastructure and IaC changes, prefer plan, eval, or check commands before applying or + deploying. -- When explicitly requested, an authentication client or command MAY consume a user-designated - secret source solely to authenticate to the specified service (e.g. an API, `redis-cli`, `psql`, - or `pgcli`). -- Secrets MUST remain opaque to the agent and must not be exposed in arguments, output, or logs; - copied, cached, or persisted; or sent anywhere except the intended authentication target. -- All other secret-value access is forbidden. Metadata and identifiers MAY be queried only with - operations verified not to reveal secret values, such as `kubectl describe secret`. +### Destructive and force operations -## 4) Scope Discipline +- Avoid irreversible operations. +- Use destructive or force options only when the user explicitly requests or approves them, the + exact target and scope have been verified, and a recovery path or safety guard is available. +- Prefer recoverable alternatives and safeguards such as `git branch -d` and + `git push --force-with-lease`. -- Keep changes strictly within requested scope. -- Do not refactor unrelated areas unless user asks. -- Preserve backward compatibility unless a breaking change is explicitly requested. +### Secrets and authentication -## 5) Change Hygiene +- Never expose or commit tokens, keys, passwords, kubeconfig credentials, or other secrets. +- Never write secret literals into tracked files. Use environment variables, secret managers, or + placeholders. +- Redact sensitive values from command output, logs, and summaries. +- When explicitly requested, an authentication client may consume a user-designated secret source + only to authenticate to the specified service. +- Keep secrets opaque. Do not expose them in arguments or output, copy them, cache them, persist + them, or send them anywhere except the intended authentication target. +- Do not access secret values for any other purpose. Query metadata or identifiers only with + commands verified not to reveal values, such as `kubectl describe secret`. -- Keep diffs minimal and reviewable. -- Group logically related edits together. -- Do not revert user/unrelated changes unless explicitly asked. -- Do not claim verification you did not run. +## Repository state -## 6) Tooling Defaults +At the start of repository work: -- Use Nushell for personal tooling, Bash for simple one-off commands, and Python for scripts or - complex control flow. -- Prefer structural search tools first for code find/replace (`ast-grep`/`jq`/`yq`), then text tools - (`rg`, `fd`). -- Prefer project task runners (`just`, `make`, `npm scripts`, etc.) over ad-hoc commands when - equivalent. -- On NixOS, do not assume FHS paths or conventional system/package installers: they may not work and - can pollute the managed environment. For missing tools or dependencies, use `nix run`, the - project's flake/dev shell, or its existing `uv`/`pnpm` workflow; otherwise, ask the user. -- Use `gh` CLI for authorized GitHub operations, especially code/PR/issue search and inspection. -- Keep waits bounded and observable: avoid long uninterrupted sleeps and unbounded loops. -- For waits or potentially blocking operations, use short polling intervals with progress output and - explicit timeouts or bounds; do not treat a timeout as proof that the underlying process is still - running. Prefer Python over Bash for custom polling logic. -- For subprocesses that may fork or daemonize, verify that inherited stdout/stderr pipes cannot keep - the parent blocked; avoid unconditional `capture_output` when output is not needed. +- Fetch `origin` when available and use its latest default branch as the baseline. +- If local history differs, ask which state to use before editing. -## 7) Environment Defaults +## Change discipline -- Primary OS: NixOS & macOS. -- Shell: default to Nushell, Bash also exists. -- Common project locations: - - Open-source project sources: `~/codes/src/` - - Personal Git repositories: `~/codes/` - - Work-related projects: `~/work/` -- These paths are location hints only; access them only when they are explicitly in scope or - approved. +- Keep work within the requested scope. Do not refactor unrelated areas unless asked. +- Preserve backward compatibility unless the user explicitly requests a breaking change. +- Keep diffs minimal, reviewable, and grouped by logical purpose. +- Do not revert user changes or unrelated changes unless explicitly asked. +- Verify changes in proportion to their risk. Never claim a check passed unless it was run. -## 8) Script Engineering Principles +### Commit messages -Treat scripts as interruptible jobs that must be diagnosable and safe to rerun: +- Follow the repository convention. Otherwise, use Conventional Commits. +- Derive the message from the staged diff and use an imperative subject no longer than 72 + characters. +- Keep one logical change per commit. Do not amend commits or skip hooks unless explicitly + requested. -- Verbose logging of progress, decisions, and errors. -- Stage workflows with selective execution via cli flags. -- Idempotent reruns; persist progress and support resume. -- Cache external data with invalidation. -- Separate HTTP transport from business success; retry with backoff. -- Verify key outputs independently. +## Tools and environment -## 9) Communication Defaults +- Primary platforms are NixOS and macOS. +- Use Nushell for personal tooling and Bash for simple one-off commands. Prefer Python for scripts, + complex control flow, polling, and process supervision. +- Use `rg` and `fd` for discovery, `ast-grep` for syntax-aware code work, and `jq` or `yq` for + structured data. +- Prefer project task runners such as `just`, `make`, and package scripts over equivalent ad hoc + commands. +- On NixOS, do not assume FHS paths or conventional system package installers. Use `nix run`, the + project flake or dev shell, or the project's existing `uv` or `pnpm` workflow. Ask before using a + different installation method. +- `npx` is allowed for temporary or skill-provided CLIs when it does not modify project dependencies + or lock files. +- Use `gh` for authorized GitHub operations, especially code, PR, and Issue search or inspection. -- Respond in the user's language; prefer English or Chinese. -- Code, commands, identifiers, and code comments: Prefer English. +## Commands and scripts + +- Prefer native wait or subscription tools. Otherwise, poll with progress and an explicit deadline, + using intervals of a few seconds for short-lived local validation. A timeout does not prove the + process is still running. +- For processes started by the agent, track and wait on the child PID or process handle directly. Do + not infer liveness by matching `ps` or `pgrep` output. +- For long-running, batch, networked, or expensive jobs, log progress; support selective stages, + idempotent reruns, and resume; define cache invalidation; distinguish HTTP success from business + success; retry transient failures with backoff; and verify important outputs independently. + +## Communication + +- Respond in the user's language. If the language is unclear, default to English or Chinese. +- Prefer English for code, commands, identifiers, and code comments. - Be concise, concrete, and action-oriented. - -## 10) Project Overlay - -Project-local policy may add stricter constraints (build/test/deploy/style/ownership/environment). -It must not weaken this baseline. diff --git a/agents/install-skills.md b/agents/install-skills.md index ad9a2294..9a5b4dfb 100644 --- a/agents/install-skills.md +++ b/agents/install-skills.md @@ -1,7 +1,7 @@ # Agent Skills Commands -Reference commands for listing, installing, and updating skills via `npx skills`. Run only the -commands you need. +Reference commands for listing, installing, and updating skills via `npx skills`. Keep the global +set small and install task-specific skills in the relevant project. ## Inspect and update installed skills @@ -17,47 +17,66 @@ npx skills check # update all installed skills npx skills update - -# remove from global scope -npx skills remove --global web-design-guidelines ``` ## Discover skills from repositories ```bash # list skills in a repository -npx skills add vercel-labs/agent-skills --list +npx skills add anthropics/skills --list ``` -## Install commonly used skill packs +## Global baseline ```bash -# superpowers +# structured planning, testing, debugging, review, and verification workflows npx skills add -g obra/superpowers --skill '*' -# github skills -npx skills add -g github/awesome-copilot --skill 'git-commit' --skill 'gh-cli' - -# find skills -npx skills add -g vercel-labs/skills - -# anthropic skills -npx skills add -g anthropics/skills --skill 'skill-creator' --skill 'pdf' +# discover task-specific skills when needed +npx skills add -g vercel-labs/skills --skill 'find-skills' ``` -## Optional packs +`find-docs` is also installed globally from a local source, so it has no upstream install command. + +## Optional global skills ```bash -npx skills add -g pbakaus/impeccable --skill '*' +# rewrite prose to sound natural while preserving claims and technical meaning +npx skills add -g blader/humanizer --skill 'humanizer' -npx skills add -g coreyhaines31/marketingskills --skill '*' +# review code for unnecessary abstractions and over-engineering +npx skills add -g DietrichGebert/ponytail --skill 'ponytail-review' -npx skills add -g phuryn/pm-skills --skill '*' +# enable a terse response mode when context or token usage matters +npx skills add -g JuliusBrussee/caveman --skill 'caveman' +``` + +## Optional project skills + +Run these commands from the project root. They intentionally omit `-g`, so the skills apply only to +the current project. Check `git status` after installation and commit the generated files only when +the whole team should use them. + +```bash +# design distinctive UI and demo pages +npx skills add anthropics/skills --skill 'frontend-design' + +# test local web applications with Playwright +npx skills add anthropics/skills --skill 'webapp-testing' + +# read, create, edit, or validate PDF files +npx skills add anthropics/skills --skill 'pdf' + +# run CodeQL and Semgrep on repositories written in supported languages; not for pure Nix projects +npx skills add trailofbits/skills --skill 'codeql' --skill 'semgrep' ``` References: +- https://github.com/obra/superpowers - https://github.com/vercel-labs/skills -- https://github.com/pbakaus/impeccable -- https://github.com/coreyhaines31/marketingskills -- https://github.com/phuryn/pm-skills +- https://github.com/blader/humanizer +- https://github.com/DietrichGebert/ponytail +- https://github.com/JuliusBrussee/caveman +- https://github.com/anthropics/skills +- https://github.com/trailofbits/skills