XzhLoongSkills/AGENTS.md

XzhLoongSkills — Agent Guidelines

What this is

A monorepo of OpenCode/Codex AI agent skills organized into category directories under skills/. Each skill is a subdirectory with a SKILL.md (YAML frontmatter: name, description) and optional scripts/, references/, assets/.

No build system, no tests, no CI. The only package.json is in skills/academic/research-skills/paper-slide-deck/scripts/ (Node deps for PDF/slide generation). No Python package manager config exists.

Repo structure

skills/
  essential/          (通用必装 — 15 skills)
  code-dev/           (代码开发 — 8 skills)
  data-science/       (数据科学与机器学习 — 11 skills)
  academic/           (学术研究 — 6 skills + research-skills 子合集)
    research-skills/  (3 单智能体 + 5 多智能体调研系统)
  office/             (文档办公 — 6 skills)
  obsidian/           (Obsidian & 知识管理 — 5 obsidian-sub + 1 wiki)

• skills/essential/ (通用必装): brainstorming, dispatching-parallel-agents, executing-plans, finishing-a-development-branch, handoff-doc, handoff-receive, handoff-review, karpathy-guidelines, planning-with-files, subagent-driven-development, systematic-debugging, using-superpowers, verification-before-completion, writing-plans, writing-skills
• skills/code-dev/ (代码开发): code-reviewer, code-simplifier, ralph-loop, receiving-code-review, requesting-code-review, test-driven-development, using-git-worktrees, ui-ux-pro-max
• skills/data-science/ (数据科学与机器学习): dask, exploratory-data-analysis, matplotlib, optimize-for-gpu, polars, pydicom, scikit-learn, seaborn, statistical-analysis, transformers, vaex
• skills/academic/ (学术研究): citation-management, paper-lookup, parallel-web, pyzotero, research-lookup, scientific-writing, research-skills/
• skills/office/ (文档办公): docx, markdown-mermaid-writing, markitdown, pdf, pptx, xlsx
• skills/obsidian/ (Obsidian & 知识管理): obsidian-skills/ (5 sub-skills), xzh-obsidian-llm-wiki

Key conventions

• Every skill must have a SKILL.md with frontmatter (name, description).
• Use <HARD-GATE> markers in SKILL.md for non-negotiable workflow gates.
• Skill descriptions should be detailed enough for the agent routing system to match correctly.
• The name in frontmatter must match the leaf directory name (e.g., name: brainstorming, not essential/brainstorming).
• scripts/ can contain Python, TypeScript, JS, or shell files; no CI enforces this.
• No formatter, linter, or typechecker config exists at root level.

Adding a new skill

1. Create skills/<category>/<name>/SKILL.md with frontmatter (name, description).
2. Choose the right category (essential/, code-dev/, data-science/, academic/, office/, or obsidian/).
3. Add an entry to README.md:
   • In the category table (under ## 技能分类)
   • In the full alphabetical table (under ## 全部技能)
4. If the skill belongs to research-skills/ or obsidian-skills/, place it inside the respective sub-collection.

Removing a skill

1. Delete skills/<category>/<name>/.
2. Remove its entries from both tables in README.md.

After adding or removing a skill

The README.md has two tables that must stay in sync with skills/:

• 分类表 (## 技能分类) — one table per category, with an install command block above
• 全表 (## 全部技能) — single alphabetical list of all skills

Rule: After any add/remove, regenerate both tables to match the actual directory structure. Do not leave stale entries.

Git repos

• GitHub: kekezack/XzhLoongSkills
• Gogs (internal China mirror): gogs.1808366.xyz/kekezack/XzhLoongSkills.git
• Branches: default master

Gotchas

• skills/academic/research-skills/ has its own .gitignore (separate from root).
• The multi-agent survey system under research-skills/skills/ uses Chinese agent role names and config files with Chinese filenames.
• paper-slide-deck requires npm install in its scripts/ directory before using TypeScript tools.