Getting Started — 快速開始

Terminology rule (zh-TW pages)

技術名詞首次出現以「中文 (English original)」格式呈現，例：依賴注入 (dependency injection)。不自創翻譯——若無公認譯名直接保留英文 （如 embedding、tokenizer）。代碼、API 名、CLI flag、套件名、檔名一律不翻。

安裝 skill

# Install all skills bundled in this repo into your project's
# .agents/skills/ directory.
npx skills@latest add daviddwlee84/agent-skills/skills

Note The trailing /skills matters. Without it, npx skills will look in .agents/skills/ of the upstream repo, which contains a different layout. The skills/ suffix points the installer at the skills/local/ and skills/vendor/ trees.

This is the recommended cross-agent install path. Project installs place the canonical skill content under .agents/skills/, which Codex reads directly; Claude Code receives its corresponding .claude/skills/ links.

Heads-up — upstream picker bug. npx skills' interactive multiselect glitches once the skill list is long enough to scroll: options render duplicated and the selection state gets corrupted (vercel-labs/skills#969). This repo ships enough skills to trigger it. Until it's fixed upstream, skip the picker:

# Install everything, non-interactively (no picker)
npx skills@latest add daviddwlee84/agent-skills/skills --yes

# List names from a disposable directory. In an existing agent-managed
# project, skills@1.5.23 may reconcile .agents/skills even with --list.
scratch="$(mktemp -d)"
(cd "$scratch" && npx skills@latest add daviddwlee84/agent-skills/skills --list)
rm -rf "$scratch"

# Install one skill by name.
npx skills@latest add daviddwlee84/agent-skills/skills --skill clash-proxy-api

Optional: native Claude Code and Codex marketplaces

A local checkout can expose the same category catalog through either native plugin CLI:

git clone https://github.com/daviddwlee84/agent-skills.git

# Claude Code
claude plugin marketplace add ./agent-skills/skills
claude plugin install version-control@daviddwlee84-skills

# Codex (verified with 0.147.0)
codex plugin marketplace add ./agent-skills/skills
codex plugin add version-control@daviddwlee84-skills

Both native routes install a whole category plugin (version-control in this example), not an arbitrary single skill. Codex reads the existing Claude-format marketplace and generates its .codex-plugin/plugin.json adapter inside the plugin cache; this repository does not need to maintain that second manifest. Keep using npx skills when you want one skill or a cross-agent installation.

Pass the checkout's skills/ directory, not the repository root: the catalog intentionally lives under skills/.claude-plugin/ for the npx subpath above, and both native CLIs require a supported manifest at the marketplace source root.

這會把這個 repo 中 skills/local/ 與 skills/vendor/ 底下的東西， 全部安裝到你 project 的 .agents/skills/。

渲染 (render) repo 自己的 backlog

如果你想看這個 repo TODO 清單的看板 (kanban) 視圖：

git clone https://github.com/daviddwlee84/agent-skills
cd agent-skills
make kanban

make kanban 會跑 scripts/todo-kanban.sh， 驗證 TODO.md 並印出依 lane 分組的 Markdown 看板。

在本機建構 docs

你正在讀的這個 docs 站是個 MkDocs Material 站。 本機預覽：

# 在 repo 根目錄
uv sync --extra docs
uv run mkdocs serve

然後打開 http://127.0.0.1:8000/。

要產生靜態站 (GitHub Pages 服務的就是這個產物)：

uv run mkdocs build

make docs-serve 跟 make docs-build 是這兩個指令的便利包裝。

把 project-knowledge-harness skill 套到你自己的 project

如果你只想要把 TODO + backlog + pitfalls 的結構帶到另一個 repo， 內建的 init script 一行搞定：

git clone https://github.com/daviddwlee84/agent-skills /tmp/agent-skills
/tmp/agent-skills/skills/local/project-knowledge-harness/scripts/init.sh \
  --target /path/to/your/project \
  --project-name "Your Project" \
  --deployment chezmoi   # 或 npm | pip | docker | none

script 做了什麼、支援哪些 flag，請看 project-knowledge-harness 頁面。