From 3283e990b2188f4080fa19d27204195cd2708ac0 Mon Sep 17 00:00:00 2001
From: Ryan Yin <xiaoyin_c@qq.com>
Date: Sat, 21 Mar 2026 22:20:50 +0800
Subject: [PATCH] docs(agents): convert install shell snippets to markdown refs

---
 agents/README.md         | 97 ++++++++++++++--------------------------
 agents/install-cli.md    | 33 ++++++++++++++
 agents/install-cli.sh    | 18 --------
 agents/install-skills.md | 63 ++++++++++++++++++++++++++
 agents/install-skills.sh | 41 -----------------
 5 files changed, 129 insertions(+), 123 deletions(-)
 create mode 100644 agents/install-cli.md
 delete mode 100644 agents/install-cli.sh
 create mode 100644 agents/install-skills.md
 delete mode 100644 agents/install-skills.sh

diff --git a/agents/README.md b/agents/README.md
index fc14479e..97e07294 100644
--- a/agents/README.md
+++ b/agents/README.md
@@ -1,59 +1,24 @@
 # agents
 
-This directory is a reusable home for agent-related files that can be shared across projects.
+Reusable, symlink-first agent resources shared across projects.
 
-The intended use is to symlink or copy files from here into different agent config directories,
-skill folders, or other agent runtimes. Treat it as a portable source of truth for important agent
-behavior and supporting materials.
+This directory is the canonical source for baseline agent rules and supporting command references.
+The primary workflow is to symlink files from here into each agent runtime/config location.
 
-It is intended to be a personal collection similar in spirit to
-[`github/awesome-copilot`](https://github.com/github/awesome-copilot), but maintained for my own
-agents, workflows, and preferences.
+## What this directory contains
 
-## Use Cases
+- `AGENTS.md`: global baseline rules for coding agents.
+- `install-rules.py`: installs the baseline by creating symlinks in supported agent config dirs.
+- `install-cli.md`: curated CLI install/update command snippets.
+- `install-skills.md`: curated `npx skills` command snippets.
 
-- shared agent rules
-- reusable prompts
-- skill definitions
-- agent templates
-- instruction packs
-- workflow notes
-- setup helpers
-- environment preparation docs
+## Core workflow
 
-## Current Files
+1. Maintain shared rules in `agents/AGENTS.md`.
+2. Run `install-rules.py` to refresh symlinks in local agent homes.
+3. Use `install-cli.md` and `install-skills.md` as reference snippets when needed.
 
-- `AGENTS.md`: baseline rules and operating constraints for agents.
-- `install-rules.py`: symlinks `AGENTS.md` into supported agent config directories.
-- `install-cli.sh`: command snippets for installing/updating common agent CLIs.
-- `install-skills.sh`: command snippets for listing/installing/updating shared skills.
-
-## Guidelines
-
-- Keep files portable across repositories when possible.
-- Prefer plain text and small reviewable files.
-- Document assumptions that downstream agent setups need to know.
-- Keep secrets and machine-specific credentials out of this directory.
-- Prefer reusable materials that can be copied, symlinked, or adapted by multiple agents.
-
-## Distribution
-
-You can:
-
-- symlink files from this directory into an agent's config or skills folder
-- copy selected files into another agent environment
-- treat this directory as the canonical source and sync outward from it
-
-## Utilities
-
-### Install shared baseline rules
-
-`install-rules.py` currently targets:
-
-- Codex: `AGENTS.md` -> `${CODEX_HOME:-~/.codex}/AGENTS.md`
-- OpenCode: `AGENTS.md` -> `${XDG_CONFIG_HOME:-~/.config}/opencode/AGENTS.md`
-- Claude Code: `AGENTS.md` -> `~/.claude/CLAUDE.md`
-- Gemini: `AGENTS.md` -> `~/.gemini/GEMINI.md`
+## Install baseline rules (symlink-based)
 
 Run:
 
@@ -61,29 +26,33 @@ Run:
 python3 agents/install-rules.py
 ```
 
-Notes:
+Current targets:
 
-- each target is handled independently
-- missing target directories are skipped
-- existing target file/symlink is replaced with a symlink to this repo copy
+- Codex: `AGENTS.md` -> `${CODEX_HOME:-~/.codex}/AGENTS.md`
+- OpenCode: `AGENTS.md` -> `${XDG_CONFIG_HOME:-~/.config}/opencode/AGENTS.md`
+- Claude Code: `AGENTS.md` -> `~/.claude/CLAUDE.md`
+- Gemini: `AGENTS.md` -> `~/.gemini/GEMINI.md`
 
-### Install or update agent CLIs
+Behavior:
 
-`install-cli.sh` is a command list (review before running):
+- Each target is handled independently.
+- Missing destination directories are skipped.
+- Existing destination file/symlink is replaced with a symlink to this repo source file.
 
-```bash
-bash agents/install-cli.sh
-```
+## About `install-cli.md` and `install-skills.md`
 
-### Install or update shared skills
+Use them as snippet libraries:
 
-`install-skills.sh` is a command list for `npx skills` workflows:
+- review the commands
+- select what you need
+- run selected commands manually
 
-```bash
-bash agents/install-skills.sh
-```
+## Conventions
+
+- Keep files portable and reviewable.
+- Keep secrets and machine-specific credentials out of this directory.
+- Keep guidance generic enough to reuse across multiple agent environments.
 
 ## Goal
 
-Build a personal, reusable library of agent resources that is easy to share across environments and
-easy to extend over time.
+Maintain one reusable source of truth for agent setup that stays simple to sync and easy to evolve.
diff --git a/agents/install-cli.md b/agents/install-cli.md
new file mode 100644
index 00000000..22d0e2f2
--- /dev/null
+++ b/agents/install-cli.md
@@ -0,0 +1,33 @@
+# Agent CLI Commands
+
+Reference commands for installing and updating agent CLIs. Run only the commands you need.
+
+## Install CLIs
+
+```bash
+# codex
+npm i -g @openai/codex
+
+# opencode
+npm install -g opencode-ai
+
+# kimi-cli
+uv tool install --python 3.13 kimi-cli
+uv tool upgrade kimi-cli --no-cache
+
+# gemini-cli
+npm install -g @google/gemini-cli
+```
+
+## Optional tooling
+
+```bash
+# context7: up-to-date docs and code examples for LLMs and agents
+npx ctx7 setup
+```
+
+## Update npm-installed agent tools
+
+```bash
+npm update -g
+```
diff --git a/agents/install-cli.sh b/agents/install-cli.sh
deleted file mode 100644
index 6d246021..00000000
--- a/agents/install-cli.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-# codex
-npm i -g @openai/codex
-
-# opencode
-npm install -g opencode-ai
-
-# kimi-cli
-uv tool install --python 3.13 kimi-cli
-uv tool upgrade kimi-cli --no-cache
-
-# gemini-cli
-npm install -g @google/gemini-cli
-
-# context7 - up-to-date docs and code examples for for LLMs & agents
-npx ctx7 setup
-
-# update all agents installed via npm
-npm update -g
diff --git a/agents/install-skills.md b/agents/install-skills.md
new file mode 100644
index 00000000..2b4f7b10
--- /dev/null
+++ b/agents/install-skills.md
@@ -0,0 +1,63 @@
+# Agent Skills Commands
+
+Reference commands for listing, installing, and updating skills via `npx skills`. Run only the
+commands you need.
+
+## Inspect and update installed skills
+
+```bash
+# list all installed skills (project + global)
+npx skills list
+
+# list only global skills
+npx skills ls -g
+
+# check for updates
+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
+```
+
+## Install commonly used skill packs
+
+```bash
+# superpowers
+npx skills add -g obra/superpowers --agent '*' --skill '*'
+
+# github skills
+npx skills add -g github/awesome-copilot --agent '*' --skill 'git-commit'
+
+# find skills
+npx skills add -g vercel-labs/skills --agent '*'
+
+# skill-creator
+npx skills add -g anthropics/skills --agent '*' --skill 'skill-creator'
+```
+
+## Optional packs
+
+```bash
+npx skills add -g pbakaus/impeccable --agent '*' --skill '*'
+
+npx skills add -g coreyhaines31/marketingskills --agent '*' --skill '*'
+
+npx skills add -g phuryn/pm-skills --agent '*' --skill '*'
+```
+
+References:
+
+- https://github.com/vercel-labs/skills
+- https://github.com/pbakaus/impeccable
+- https://github.com/coreyhaines31/marketingskills
+- https://github.com/phuryn/pm-skills
diff --git a/agents/install-skills.sh b/agents/install-skills.sh
deleted file mode 100644
index 1cc8130d..00000000
--- a/agents/install-skills.sh
+++ /dev/null
@@ -1,41 +0,0 @@
-# https://github.com/vercel-labs/skills
-
-# List all installed skills (project and global)
-npx skills list
-
-# List only global skills
-npx skills ls -g
-
-# Check if any installed skills have updates
-npx skills check
-
-# Update all skills to latest versions
-npx skills update
-
-# Remove from global scope
-npx skills remove --global web-design-guidelines
-
-# =========================================
-
-# List skills in a repository
-npx skills add vercel-labs/agent-skills --list
-
-# superpowers
-npx skills add -g obra/superpowers --agent '*' --skill '*'
-# github skills
-npx skills add -g github/awesome-copilot --agent '*' --skill 'git-commit'
-# find skills
-npx skills add -g vercel-labs/skills --agent '*'
-# skill-creator
-npx skills add -g anthropics/skills --agent '*' --skill 'skill-creator' 
-
-# frontend
-# https://github.com/pbakaus/impeccable
-# npx skills add -g pbakaus/impeccable --agent '*' --skill '*' 
-
-# https://github.com/coreyhaines31/marketingskills
-# npx skills add -g coreyhaines31/marketingskills --agent '*' --skill '*'
-
-# https://github.com/phuryn/pm-skills
-# npx skills add -g phuryn/pm-skills --agent '*' --skill '*'
-