nf-core · edmundmiller · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md
+
+> Table of contents for agents working in this repository. Keep this file short — point at deeper docs, do not duplicate them.
+
+This repository is a portable [Agent Skills](https://agentskills.io/specification) package for [nf-core](https://nf-co.re). It is consumed by Claude Code, Codex CLI, OpenCode, Cursor, and any other skills-compatible harness.
+
+## Map
+
+- [`README.md`](README.md) — install and usage.
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — repository layout and how harnesses load these skills.
+- [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) — how to add or modify a skill.
+- [`skills/`](skills/) — one directory per skill, each with a `SKILL.md`.
+
+## Operating principles
+
+1. **Skills are the unit of work.** Each capability lives in `skills/<name>/SKILL.md` with a tight YAML frontmatter (`name`, `description`) so harnesses can route to it.
+2. **Progressive disclosure.** Keep `SKILL.md` under ~500 lines. Push detail into `references/` and load it only when needed.
+3. **Portable first.** The `skills/` tree must work unmodified across Claude Code, Codex CLI, OpenCode, and Cursor.
+4. **Repository is the source of truth.** If guidance for an agent isn't in this repo, it doesn't exist. Promote tribal knowledge into a skill or a `docs/` page.
diff --git a/README.md b/README.md
@@ -11,10 +11,63 @@
 [![Watch on YouTube](http://img.shields.io/badge/youtube-nf--core-FF0000?labelColor=000000&logo=youtube)](https://www.youtube.com/c/nf-core)
 
 ## About
-This repository contains the official AI agent context files for developing nf-core pipelines. The repository aims to enable swift updates as the field evolves and the community discovers specific agent behaviour.
+
+This repository contains the official AI agent context files and [Agent Skills](https://agentskills.io/specification) for developing nf-core pipelines, modules, subworkflows, and using the nf-core toolchain. It aims to enable swift updates as the field evolves and the community discovers specific agent behaviour.
+
+The skills follow the [Agent Skills specification](https://agentskills.io/specification) so they can be used by any skills-compatible agent, including Claude Code, Codex CLI, OpenCode, and Cursor.
 
 ## Repository rules
+
 Adding or editing files in this repository requires approval from an nf-core core member (or maintainer with special permissions) and can only be done via pull requests.
 
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| [nf-core-pipeline](skills/nf-core-pipeline) | Create and modify [nf-core pipelines](https://nf-co.re/docs/contributing/pipelines) following community standards |
+| [nf-core-lint](skills/nf-core-lint) | Run and interpret `nf-core pipelines lint` to validate pipeline compliance |
+| [nf-core-module](skills/nf-core-module) | Create, modify, lint, and test nf-core modules and subworkflows with nf-core/tools 4.x conventions |
+| [nf-core-containers](skills/nf-core-containers) | Choose, pin, validate, and troubleshoot nf-core containers and software dependencies |
+
+## Installation
+
+### Claude Code
+
+```text
+/plugin marketplace add nf-core/agents
+/plugin install nf-core@nf-core-agents
+```
+
+### Codex CLI
+
+Copy the `skills/` directory into your Codex skills path (typically `~/.codex/skills`).
+
+### OpenCode
+
+Clone the repository into the OpenCode skills directory:
+
+```sh
+git clone https://github.com/nf-core/agents.git ~/.opencode/skills/nf-core-agents
+```
+
+OpenCode auto-discovers `SKILL.md` files under `~/.opencode/skills/`.
+
+### Cursor
+
+Place the repository contents under `.cursor/skills/` in your project (or globally where Cursor reads skills from).
+
+### Manual
+
+Drop the `skills/` directory contents into any agent harness that follows the [Agent Skills specification](https://agentskills.io/specification).
+
 ## Files in this repository
-- `AGENTS.md`: main agent context file containing instructions for the nf-core pipeline template.
+
+- [`AGENTS.md`](AGENTS.md): table of contents for agents working in this repository.
+- [`skills/`](skills): one directory per skill, each with a `SKILL.md`.
+- [`docs/`](docs): repository-internal documentation ([architecture](docs/ARCHITECTURE.md), [contributing](docs/CONTRIBUTING.md)).
+
+See [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) for how to add or modify a skill and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the repository layout.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -0,0 +1,33 @@
+# Architecture
+
+This repository is a flat collection of [Agent Skills](https://agentskills.io/specification). There is no application code — the "product" is the `skills/` tree.
+
+## Layout
+
+```tree
+.
+├── AGENTS.md                    # entry point for agents (table of contents)
+├── README.md                    # entry point for humans
+├── docs/                        # repository-internal documentation
+│   ├── ARCHITECTURE.md          # this file
+│   └── CONTRIBUTING.md          # how to author a skill
+└── skills/                      # the portable Agent Skills payload
+    └── <skill-name>/
+        ├── SKILL.md             # required: frontmatter + instructions
+        ├── references/          # optional: progressive-disclosure docs
+        ├── scripts/             # optional: executable helpers
+        └── assets/              # optional: templates, schemas, fixtures
+```
+
+## Harness integration
+
+Each harness consumes the same `skills/` tree:
+
+| Harness     | How it loads skills                             |
+|-------------|-------------------------------------------------|
+| Claude Code | `/plugin marketplace add` (see README)          |
+| Codex CLI   | Reads `~/.codex/skills/<name>/SKILL.md`          |
+| OpenCode    | Auto-discovers `~/.opencode/skills/**/SKILL.md`  |
+| Cursor      | Project-local `.cursor/skills/`                 |
+
+Keep the `skills/` tree free of harness-specific files — it is the portable contract.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,37 @@
+# Contributing a skill
+
+## Add a new skill
+
+1. Create `skills/<skill-name>/SKILL.md`. The directory name MUST match the `name` frontmatter field.
+2. Write the frontmatter:
+
+   ```yaml
+   ---
+   name: skill-name
+   description: One or two sentences. State both *what* the skill does and *when* the agent should use it. Include keywords the agent will pattern-match on.
+   license: MIT
+   metadata:
+     author: nf-core
+     version: "0.1.0"
+   ---
+   ```
+
+3. Write the body. Aim for under 500 lines. Move long material to `skills/<skill-name>/references/<TOPIC>.md` and link to it.
+4. Run the validator:
+
+   ```sh
+   skills-ref validate skills/<skill-name>
+   ```
+
+5. Add a row to the Skills table in [`README.md`](../README.md).
+
+## Style
+
+- **Imperative, terse.** The reader is an agent, not a human reviewer.
+- **Lead with "When to use" and "When not to use".** Routing accuracy matters more than completeness.
+- **Show commands, not prose.** Code blocks are first-class.
+- **No backstory.** Anything historical or motivational belongs in a design doc, not a skill.
+
+## Progressive disclosure
+
+The agent loads `name` + `description` for every skill at startup, the full `SKILL.md` only when activated, and files in `references/` / `scripts/` / `assets/` only when explicitly referenced. Structure your skill to take advantage of all three tiers.