tool_skills_test

Cursor Agent Skills for scientific-tool pitfalls, generated from GitHub-issue-derived markdown reports.

Python 3.10+ required. The build script has no third-party dependencies (aliases YAML is parsed with a tiny built-in subset reader).

Skill only vs submitting updates

Goal	What you need
Use pitfall knowledge in Cursor	Install the skill only: copy or symlink e.g. skills/fusion-equilibrium-pitfalls/ into ~/.cursor/skills/ or .cursor/skills/. You do not need to clone this repository.
Contribute and open a PR	Clone the repo (usually your fork) into ~/tool_skills_test by default — run merge + build from that repo root, then commit sources/, skills/, and data/.

Clone location (convention)

Contributors and agents using this workflow should use a single default working copy under the home directory:

• Path: ~/tool_skills_test ($HOME/tool_skills_test).
• Clone: from the repo root in all instructions below, or explicitly:

git clone https://github.com/fancaiyu/tool_skills_test.git ~/tool_skills_test
cd ~/tool_skills_test

Use your fork URL if you open PRs from a fork. If that directory already exists, remove or rename it first, or clone to another path and tell the agent the absolute path (see scientific-pitfall-contribute skill Step 0).

Domains

A domain is an application / scientific field (how pitfalls are grouped into one installable skill), not a single library name. Example: fusion-equilibrium → skills/fusion-equilibrium-pitfalls/. Tool names belong in sources/<domain>/{Tool}.md, not as the domain slug (avoid creating jax / pytorch domains unless you intentionally add a new field with maintainer agreement).

Each domain has:

• Human-edited source trees: sources/<domain-slug>/*.md (踩坑大全 format, one file per primary tool name).
• Registry: config/domains.json — maps each slug to skill_out, records path, skill id/title (skill_name, skill_title), and machine-oriented tool lists: domain_tools (native catalogue — use this for field membership) and cross_tools (co-tools in multi-tool pitfalls recorded here — not membership; do not route new contributions from cross_tools alone). Both lists are rewritten on each build_pitfall_skill.py run for that slug (omit --no-update-domains in normal workflows).
• One generated installable skill per domain (e.g. skills/fusion-equilibrium-pitfalls/). The skill’s SKILL.md mirrors the same tool lists for humans; agents routing pitfalls should prefer domains.json.

To add a new field domain: agree a field-level slug, create sources/<slug>/, add a matching entry to config/domains.json (paths + skill_name / skill_title; you may omit domain_tools / cross_tools until the first build fills them), then run python3 scripts/build_pitfall_skill.py --domain <slug>.

When choosing or inventing a field, go by which community this repo uses to catalogue the involved tools (tool → field), not by keywords in one pitfall (e.g. TPU/GPU/accelerator mentions in an issue do not justify a domain like ml-accelerators if the maintainers do not place that tool family there). Put incident-specific terms in the pitfall body or keywords, not in the domain slug.

Layout

Path	Purpose
config/domains.json	Domain list, paths, domain_tools / cross_tools (auto-updated on build).
sources/<domain>/	Markdown reports for that domain only.
config/tool_aliases.yaml	Maps lowercase **Tools involved:** tokens to canonical slugs (updated on each build unless --no-update-aliases).
scripts/build_pitfall_skill.py	Builds one domain’s skill from its sources/<domain>/ tree.
scripts/merge_contributions.py	Merges contribution YAML into sources/<domain>/{Tool}.md.
schemas/pitfall-entry.schema.json	JSON Schema for one pitfall record (JSONL).
skills/…	Generated installable skills (copy into ~/.cursor/skills/).
scientific-pitfall-contribute/	Cursor skill for the contribution flow (use with a cloned repo).

Build a domain skill

From the repo root (default working copy ~/tool_skills_test):

cd ~/tool_skills_test
python3 scripts/build_pitfall_skill.py --domain fusion-equilibrium

Build every registered domain:

python3 scripts/build_pitfall_skill.py --all-domains

Default domain (when --domain is omitted) is fusion-equilibrium if present in domains.json, otherwise the first domain key alphabetically.

Ad-hoc layout (no domains.json entry): pass all of --sources-dir, --out, and --records.

Explicit file list:

python3 scripts/build_pitfall_skill.py --domain fusion-equilibrium \
  --inputs sources/fusion-equilibrium/DESC.md

Do not write tool_aliases.yaml (CI or dry check):

python3 scripts/build_pitfall_skill.py --domain fusion-equilibrium --no-update-aliases

Do not rewrite config/domains.json tool lists (rare):

python3 scripts/build_pitfall_skill.py --domain fusion-equilibrium --no-update-domains

Rules enforced by the generator:

• Single-tool entries → reference/by-tool/<Tool>.md only.
• Multi-tool entries → reference/cross/<ToolA>__<ToolB>[__<ToolC>...].md only.
• cross_index.json lists each cross file and its tools array.
• Tools that appear only in cross entries have no reference/by-tool/<Tool>.md; use cross_index.json + reference/cross/ for those (see generated SKILL.md).

Contributing a pitfall

Contributors need a local clone at ~/tool_skills_test unless you agree another path with your tooling. Upstream: https://github.com/fancaiyu/tool_skills_test.git — fork for PRs if you are not a direct collaborator. See .github/pull_request_template.md.

1. Be in a real clone at the repo root (default ~/tool_skills_test — see Clone location (convention) and contribute skill Step 0): if clone fails, retry; do not fabricate the tree. Domain slugs and tool lists come from config/domains.json — not from scanning installed skills’ reference/ folders.
2. Use the scientific-pitfall-contribute skill (or hand-write the same fields) and save a temporary YAML under contributions/incoming/<slug>.yaml (gitignored).
3. Resolve domain (see contribute skill): the agent (or you) must confirm with a human which field slug(s) each tool belongs in before merge/build — then infer paths from sources/<domain>/{Tool}.md or pass --domain <slug>; for a new domain, agree the slug, add config/domains.json + sources/<slug>/, then merge after approval.
4. Validate, merge into every domain that applies, then build only those domains (not necessarily --all-domains). If listed tools catalogue under two or more distinct domains, merging into each is required — see contribute skill Mandatory — cross-field pitfalls.

Single domain:

cd ~/tool_skills_test
python3 scripts/validate_contribution.py contributions/incoming/your-slug.yaml
python3 scripts/merge_contributions.py --domain fusion-equilibrium contributions/incoming/your-slug.yaml
python3 scripts/build_pitfall_skill.py --domain fusion-equilibrium

Same pitfall in multiple domains (separate sources/<domain>/{Tool}.md files; dedup is per file, not across domains or data/*.jsonl):

cd ~/tool_skills_test
python3 scripts/merge_contributions.py \
  --domain fusion-equilibrium \
  --domain <other-slug> \
  contributions/incoming/your-slug.yaml
python3 scripts/build_pitfall_skill.py --domain fusion-equilibrium --domain <other-slug>

If config/domains.json changed, include it in the PR.

5. Commit sources/, skills/, data/, and config/domains.json when changed (see scientific-pitfall-contribute/SKILL.md).

Optional: pip install PyYAML for full YAML parsing in merge_contributions.py (otherwise it uses the same minimal parser as validate_contribution.py).

Upstream

• Bulk pitfall markdown may come from a separate issues collector; place or merge files under the right sources/<domain>/ before rebuilding.