Tensor Network Research

A research-grade Agent Skill that turns any compatible AI coding agent into an expert assistant for tensor network science — tensor algebra, decompositions, manifold optimization, tensor-network algorithms (DMRG, TEBD, TDVP, PEPS, MERA), tensor-network machine learning (Born machines, tensorized transformers, LLM compression), numerical linear algebra, and the surrounding paper-reading and paper-writing workflow.

Works with any agent that supports the SKILL.md standard. No dependencies, no installation step, no network calls.

---

Contents

• What this is
• What you can do with it
• Installation
  • Generic install (works for any agent)
  • Common agent skill directories
  • Verify it works
• How to use
  • Mode 1 — Auto-trigger (the usual way)
  • Mode 2 — Explicit mention
  • Mode 3 — Force-load with @
• How it works internally
• Project structure
• Customize or extend
• Contributing
• Citation
• Acknowledgments

---

What this is

An Agent Skill is a directory containing a SKILL.md file with a YAML frontmatter. The agent reads the frontmatter at startup, injects the name and description into its system prompt, and uses the description to decide when to load the rest of the skill. The skill then provides deep, structured knowledge plus a routing table that points the agent to the right reference material for each sub-question.

The SKILL.md standard is supported by a growing number of agent runtimes. The same skill file works across all of them with no modification.

This particular skill targets the tensor network research community — graduate students, postdocs, faculty, and applied scientists working on tensor decompositions, tensor-network algorithms, tensor-network machine learning, and the related numerical optimization and scientific writing tasks.

The full knowledge base covers:

• Tensor algebra: modes, products, ranks, norms, contractions, Einstein notation.
• Tensor decompositions: CP, Tucker, HOSVD, HOOI, Tensor Train, Tensor Ring, Hierarchical Tucker, PEPS, MERA, LPS, plus randomized, streaming, sparse, nonnegative, and orthogonal variants.
• Tensor optimization: Riemannian and manifold optimization, ALS, block coordinate descent, proximal methods, trust-region, projected gradient, Burer–Monteiro, plus convergence theory (Łojasiewicz, KL).
• Tensor networks: MPS, MPO, PEPS, MERA, LPS, DMRG, TEBD, TDVP, canonical forms, area law, entanglement entropy.
• TN machine learning: Born machines, Neural Quantum States, tensorized neural networks, LoRA, TT-LoRA, tensorized transformers, LLM compression.
• Numerical linear algebra: SVD, QR, EVD, polar decomposition, randomized SVD, Lanczos, Arnoldi, conditioning, preconditioning, matrix completion.
• Scientific computing: NumPy, SciPy, PyTorch, JAX, TensorFlow, MATLAB, TensorNetwork, ITensor, TeNPy, quimb, opt_einsum — with code templates.
• Proof, paper reading, paper writing: PRX / JMLR / NeurIPS / ICML / ICLR / Nature style, with LaTeX templates.

---

What you can do with it

Ask the agent to…	Modules it consults
Derive the HOSVD truncation error bound, step by step.	references/01-tensor-algebra.md, 02-tensor-decompositions.md
Help me choose between CP, Tucker, and TT for a 4-D tensor of shape $100^4$ with true rank around 20.	references/02-tensor-decompositions.md
Prove that Riemannian gradient descent on the Grassmann manifold converges to a stationary point.	references/03-tensor-optimization.md, 06-numerical-linear-algebra.md
Walk me through how DMRG computes the ground state of a Heisenberg chain, with the effective Hamiltonian.	references/04-tensor-networks.md
Show me how to compress a 7B LLM with TT-LoRA, with code.	references/05-tn-machine-learning.md, templates/code-templates.md
Critique the convergence proof in this paper.	references/08-proof-assistance.md, workflows/proof-workflow.md
Summarize the contributions and weaknesses of Novikov 2015.	references/09-paper-reading.md, workflows/paper-reading-workflow.md
Help me write the methods section of a JMLR paper on Riemannian CP.	references/10-paper-writing.md, workflows/paper-writing-workflow.md
Why does my CP-ALS converge to a swamp?	references/02-tensor-decompositions.md, mistakes/common-mistakes.md
What library should I use for a 2-D PEPS ground state search?	references/libraries.md, 04-tensor-networks.md

See capabilities.md for the full task → file map.

---

Installation

The skill is just a directory of Markdown files. There is nothing to compile, build, or install via a package manager. After installing, quit and restart your agent so it re-scans the skill directories. The running session keeps using the previously loaded config until then.

The destination folder name must match the name in the SKILL.md frontmatter — in this case, tensor-network-research (lowercase, hyphen-separated).

Generic install (works for any agent)

Replace <agent-skill-dir> in the commands below with the skill directory of your agent (see the table further down for common choices).

# 1. Get the skill
git clone https://github.com/haotong-Duan/tensor-network-research.git
# or download the repo as a ZIP and extract it.

# 2. Copy it into your agent's skill directory.
#    Replace <agent-skill-dir> with your agent's actual path —
#    see the table in the next section.
mkdir -p <agent-skill-dir>
cp -R tensor-network-research <agent-skill-dir>/

# 3. Restart your agent so it picks up the new skill.

For a single project only, prefix the destination with the project directory instead of your home directory (e.g. <project-dir>/.your-agent/skills/).

Note. The placeholders <agent-skill-dir> and <project-dir> are intentional — every agent uses a different path convention. Pick the one that matches your agent from the table below. If your agent is not listed, check its documentation for the equivalent path.

Common agent skill directories

These are the directories that popular agents scan for SKILL.md files. The folder name tensor-network-research is part of the path because the name in the frontmatter must match the directory name.

Agent / family	Global path	Project path
Generic placeholder	~/.config/<agent-name>/skill/	./.<agent-name>/skill/
agent-A (style 1)	~/.config/agent-A/skill/	./.agent-A/skill/
agent-A (style 2)	~/.agent-A/skills/	./.agent-A/skills/
agent-A (style 3)	~/Library/Application Support/agent-A/skills/	./.agent-A/skills/

Two common conventions to be aware of:

• Plural skills vs. singular skill — both are used; check the agent's docs.
• ~/.config/<name> vs. ~/.<name> — both are used; some agents prefer the XDG-style config dir, others a hidden dotfile in the home directory.

If you are unsure, the safest path is to look inside your agent's config directory (e.g. ~/.config/, ~/.<agent>/, or wherever the agent stores its settings) for an existing skill or skills folder. If none exists, create one following the pattern of the agent's other config folders.

After copying, the layout on disk should look like:

<agent-skill-dir>/
└── tensor-network-research/        <- this folder
    ├── SKILL.md
    ├── README.md
    ├── capabilities.md
    ├── references/
    ├── workflows/
    ├── templates/
    └── mistakes/

Verify it works

After restarting the agent, ask a question that should clearly hit the skill:

"Explain the quasi-best approximation guarantee of TT-SVD and give me the Oseledets bound."

If the skill is loaded, the agent will (a) reference references/02-tensor-decompositions.md and references/formula-library.md in its routing, and (b) cite Oseledets 2011 with the $\sqrt{d-1}$ factor.

If the agent answers generically without the routing, the skill did not load. Common causes:

• Folder name does not match name: in SKILL.md frontmatter — must be exactly tensor-network-research (lowercase, hyphen-separated).
• You did not restart the agent.
• The destination directory is not the one your agent actually scans. Confirm by checking the agent's documentation, and verify with ls <agent-skill-dir>/tensor-network-research/SKILL.md that the file is in place.

---

How to use

There are three ways to use a Skill, ordered from most common to most explicit.

Mode 1 — Auto-trigger (the usual way)

Just ask a tensor-network question. The agent sees the description in SKILL.md frontmatter at startup; when the question matches the trigger keywords, the agent loads the skill on its own.

The skill is built to trigger on phrases like:

• "tensor decomposition", "CP rank", "TT rank", "HOSVD", "ALS for tensor"
• "matrix product state", "MPS", "tensor train", "PEPS", "MERA", "DMRG", "Born machine", "tensorized transformer"
• "Riemannian optimization on Grassmann", "fixed-rank manifold", "Lojasiewicz / KL convergence"
• "tensor completion", "TT-SVD", "tensorized attention", "LoRA for LLMs"
• "ground state search", "entanglement entropy bound"

Ask freely. The agent routes to the right references/ and workflows/ files internally.

Example prompts that will auto-load the skill:

• "I have a 3-mode tensor of shape $50 \times 50 \times 50$ with CP rank around 5. Should I use CP-ALS or Riemannian CP? What are the trade-offs?"
• "Why does my DMRG ground state energy not converge for a 1-D Heisenberg chain at bond 100?"
• "Derive the HOSVD truncation error bound. Show all steps."
• "Help me write a rebuttal to reviewer 2 on a TT-LoRA paper."

Mode 2 — Explicit mention

Tell the agent to use the skill:

"Use the tensor-network-research skill to design a CP-ALS benchmark suite."

This is helpful when the question is borderline and you want to force activation.

Mode 3 — Force-load with @

Some agents support an @skill-name syntax to inject the full skill into the context. Useful for short, sharp questions where you want all the knowledge modules on the table at once.

"@tensor-network-research What manifold optimization algorithm should I use for the fixed-rank PSD matrix completion problem in my application?"

---

How it works internally

1. Startup scan. The agent walks the skill directories (configurable per agent) and reads every SKILL.md frontmatter.
2. Description in context. The skill's name and description are injected into the agent's system prompt.
3. Routing. When a user prompt matches the description, the agent loads the skill's SKILL.md body. The body contains a "When to load sub-files" table that maps question types to specific references/, workflows/, and templates/ modules.
4. On-demand file reads. The agent reads only the files it needs, not the entire skill. This keeps the context budget manageable.
5. Reasoning principles. The skill enforces a fixed reasoning style: explicit symbols, dimension checks, complexity reporting, numerical-stability notes, and a "no hand-waving" rule. The agent is instructed to surface these in every response.

The skill is a pure-knowledge skill — it does not execute code, run experiments, or modify files. Pair it with a coding-capable agent for full research workflows.

---

Project structure

tensor-network-research/
├── SKILL.md                          <- main file, loaded by the agent
├── README.md                         <- this file
├── capabilities.md                   <- task → file map
├── .gitignore
├── references/                       <- deep knowledge modules
│   ├── 01-tensor-algebra.md
│   ├── 02-tensor-decompositions.md   <- CP, Tucker, TT, TR, HT, PEPS, MERA, ...
│   ├── 03-tensor-optimization.md     <- Riemannian, ALS, KL convergence, ...
│   ├── 04-tensor-networks.md         <- MPS, PEPS, DMRG, TEBD, TDVP, ...
│   ├── 05-tn-machine-learning.md     <- Born machines, LoRA, LLM, ...
│   ├── 06-numerical-linear-algebra.md
│   ├── 07-scientific-computing.md    <- PyTorch, JAX, TeNPy, quimb, ...
│   ├── 08-proof-assistance.md
│   ├── 09-paper-reading.md
│   ├── 10-paper-writing.md           <- PRX / JMLR / NeurIPS / ...
│   ├── glossary.md
│   ├── notation.md
│   ├── formula-library.md
│   ├── textbooks.md
│   ├── seminal-papers.md
│   ├── recent-papers.md
│   ├── libraries.md
│   ├── datasets.md
│   └── repositories.md
├── workflows/                        <- step-by-step processes
│   ├── reasoning-checklist.md
│   ├── implementation-checklist.md
│   ├── paper-reading-workflow.md
│   ├── paper-writing-workflow.md
│   ├── proof-workflow.md
│   ├── algorithm-design-workflow.md
│   ├── coding-workflow.md
│   └── experiment-workflow.md
├── templates/                        <- reusable patterns
│   ├── prompt-templates.md
│   ├── code-templates.md
│   └── reference-templates.md
└── mistakes/
    └── common-mistakes.md

35 files. ~9,000 lines of curated content. Modular, hierarchical, and easy to extend — adding a new decomposition means appending a section to references/02-tensor-decompositions.md, not rewriting the skill.

---

Customize or extend

The skill is designed to be modified.

• Add a new decomposition: open references/02-tensor-decompositions.md and add a section in the same format as the others (definition, math, pros, cons, complexity, applications, tips, pitfalls). The agent will pick it up automatically.
• Add a new paper to citations: append to references/seminal-papers.md or references/recent-papers.md.
• Add a new library: append to references/libraries.md.
• Tighten the trigger keywords: edit the description field in SKILL.md frontmatter. Be specific — front-load the literal phrases you want to match. Restart the agent after.
• Add a new workflow: create a new file under workflows/ following the structure of the existing eight. Reference it from SKILL.md and capabilities.md if you want it surfaced in the routing table.
• Translate: copy any file to <filename>.zh.md (or another locale) and translate. The skill is fully Markdown.

After editing, restart the agent. Hot-reload is not supported.

---

Contributing

Issues and pull requests welcome. Please:

• Match the file's existing style. Each references/ module is consistent within itself; follow its conventions.
• For new knowledge, prefer extending an existing module over creating a new file.
• Run a sanity check before submitting: pick a question, ask the agent, and confirm the answer references the file you edited.

For substantial changes (new module, new workflow), open an issue first to discuss the design.

---

Citation

The skill builds on the work of the tensor network community; please cite the original papers, books, and software you use (see references/seminal-papers.md, references/recent-papers.md, references/textbooks.md, and references/libraries.md).

---

Acknowledgments

Built on the work of the tensor network research community. Special thanks to the authors of the canonical references in references/seminal-papers.md — Kolda & Bader, Oseledets, Schollwöck, Orus, Cirac, Verstraete, Absil, Vandereycken, Stoudenmire, Novikov, Cichocki, and many others. See the respective files for full attribution.