# 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.