Skip to content

Bootstrap Hadron in Claude Code

MCP onlyBeginner~10 min

This page is the one-stop setup for using Hadron with a coding agent. After following it you can save knowledge to Hadron memories from any Claude Code session, and you can publish Hadron task nodes as Claude Code skills with a single instruction to the agent.

This page is for the coding-agent use case specifically. It uses OAuth and a user-level MCP configuration, so a single sign-in gives Claude Code access to every Hadron app, agent, and memory on your account, regardless of which project directory you open. If you're looking to wire Hadron into a single project directory with an app key instead, see Install Hadron with the install script — that path is appropriate for non-coding MCP hosts, not for coding agents.

The steps below can be followed by you, or by an AI coding agent acting on your behalf. You'll still need to do two things yourself: click Approve in your browser when the OAuth window opens during Step 1, and restart Claude Code at the end. Everything else — running the install command and writing the skill file — can be done by you or by an agent you've pointed at this page.

What you'll have at the end

  • A user-level hadron MCP server registered in Claude Code with the hadron_* tools available in every session.
  • A bootstrap skill at ~/.claude/skills/hadron-export-task-as-claude-skill/SKILL.md that lets you publish any Hadron task node as a Claude Code skill by asking the agent in plain English.
  • A row in your portal API-keys page with a source badge reading OAuth: dcr_…<client> — the token Claude Code is using.

What you need

Step 1 — Add the Hadron MCP server

Register Hadron as a user-level MCP server in Claude Code. Run this from any terminal:

claude mcp add --transport http hadron https://srv.hadronmemory.com/mcp

This adds hadron to your user-level Claude Code config (it applies across all projects on your machine). No project directory needs to be involved.

The OAuth dance happens on the first Hadron tool call — Claude Code opens your browser, you sign in to Hadron (via GitHub if you haven't already), review the consent screen, click Approve, and Claude Code stores the access token. You will not be asked again until the token is revoked.

For deeper detail on the OAuth flow, local-development tunnels, and multi-App users, see Install Hadron in Claude Code.

Step 2 — Install the bootstrap skill

The skill is a single file you save to a known location. You have two ways to install it:

  • Manually. Create the directory ~/.claude/skills/hadron-export-task-as-claude-skill/ and save the content below as SKILL.md inside it.

  • Via an AI coding agent. Ask Claude Code (or another coding agent with web-fetch and file-write tools) to install the skill for you. Example prompt:

    Read https://docs.hadronmemory.com/how-to/bootstrap-claude-code/ and install the skill file from Step 2 to my user-level Claude Code skills directory.

    The agent fetches this page, reads the content below, and writes it to the right location for you.

The file content is exactly this:

This is a simplified copy; the canonical procedure is the node

The skill below is transcribed from hrn:node:hadronmemory.com:core:export-task-as-claude-skill, which is the source of truth and is kept fuller than this copy. It additionally covers the provenance hash in the generated header, the rule that a description over 1024 characters takes a node out of export rather than being shortened, and why the node must be read with a batch read (a single-ref read compiles Mustache and silently strips placeholders).

The practical consequence of the difference: files written from the copy below carry the pre-#580 header with no hash, so hadron skill status reports them unhashed and cannot detect drift. That is a warning, not a failure. Read the node when you want the full procedure, and let hadron skill status judge the result either way.

---
name: hadron-export-task-as-claude-skill
description: Export a Hadron task node as an Anthropic Claude Code skill (SKILL.md file). Use when the user says "export this Hadron task as a skill", "publish <node> as a skill", "generate a SKILL.md from <urn>", "sync skill from <node>", or similar. Requires a runnable node declaring properties.exports.claudeSkill with name, description and enable set to true. Handles the gotchas — a declaration without enable publishes nothing, missing properties stop the export, overwrites existing SKILL.md (source of truth is the node), and writes user-global by default.
---

<!-- Generated from hrn:node:hadronmemory.com:core:export-task-as-claude-skill -->
<!-- Edit the source node and re-export; do not edit this file directly. -->

# Export a Hadron Task Node as a Claude Skill

Procedure for converting a Hadron `task` node into an Anthropic Claude Code
skill — a `SKILL.md` file inside a `.claude/skills/<name>/` directory.

## When to use

When the user asks to export, publish, sync, or generate a skill from a
Hadron node — e.g. "export `<urn>` as a skill," "publish this task as a
SKILL.md," "sync the `<name>` skill from Hadron."

## Inputs

- **Source URN** (required) — the Hadron node to export. Always fully
  qualified, e.g. `hrn:node:hadronmemory.com:hadron-mcp:add-node`.
- **Target location** (optional, default user-global):
    - `user` → `~/.claude/skills/<name>/SKILL.md` (default; persists across
      projects, doesn't ship in repos).
    - `project` → `<repo-root>/.claude/skills/<name>/SKILL.md`
      (version-controlled with the codebase).

## Prerequisites the source node MUST satisfy

1. `isRunnable: true`. **`nodeType` is not the gate** — `task` is the
   convention and reads clearly, but runnability is what decides.
2. `properties.exports.claudeSkill.name` — kebab-case, ≤64 chars, used as the
   skill name and directory name. Stored whole and used verbatim; nothing
   derives or prefixes it.
3. `properties.exports.claudeSkill.description` — trigger-shaped description
   ("Use when… Handles the gotchas…"), **≤1024 chars**, used as the SKILL.md
   `description` that drives auto-trigger. The host truncates a longer one in
   its listing, so trigger phrases past the cut never fire.
4. `properties.exports.claudeSkill.enable == true`. **Export defaults to
   OFF** — a declaration without it publishes nothing.

If any of these are missing or malformed, **stop and report to the user**.
Do not invent values; the node is the source of truth.

The retired top-level `properties.claudeSkill` / `properties.skill` keys are
still read as aliases, but they never carry `enable`, so a node on them reads
as disabled. Migrate it — move the object under `exports` and add
`enable: true` — rather than exporting around it.

## Procedure

### Step 1 — Read the source node

```
hadron_get_node urn:<source>
```

### Step 2 — Validate

Confirm all three prerequisites above. On failure, report which prerequisite
is missing and stop.

### Step 3 — Determine output path

Resolve `<name>` from `properties.exports.claudeSkill.name`. Resolve
`<skills-root>` from the target-location argument:

- `user` → `$HOME/.claude/skills`
- `project` → `<current-repo-root>/.claude/skills`

Final path: `<skills-root>/<name>/SKILL.md`.

Create parent directories if missing.

### Step 4 — Compose the SKILL.md content

```markdown
---
name: <properties.exports.claudeSkill.name>
description: <properties.exports.claudeSkill.description>
---

<!-- Generated from <source URN> -->
<!-- Edit the source node and re-export; do not edit this file directly. -->

<node `content` body, verbatim>
```

Preserve the node body exactly. Do not reflow, summarize, or add headings.

### Step 5 — Write the file

Write to the resolved absolute path. Overwrite if the file exists — the
node is the source of truth, and editing the SKILL.md directly is
explicitly discouraged by the provenance comment.

### Step 6 — Report to the user

Tell the user:

- The absolute path that was written.
- The skill `name` and `description` that will trigger it.
- Reminder: Claude Code loads skills at session start; existing sessions
  may need to restart to pick up a new or updated skill.

## Gotchas

- **Source of truth is the node, not the SKILL.md.** If the user wants to
  edit a skill's behavior, edit the node and re-export. The provenance
  comment in the generated file makes this contract visible.
- **Don't write back into the node from the SKILL.md.** This is a one-way
  publishing pipeline.
- **Preserve case.** Skill names are case-sensitive; use the exact
  `properties.exports.claudeSkill.name` verbatim.
- **No frontmatter in the node body.** The node's `content` is the SKILL.md
  body, not the whole SKILL.md. Frontmatter is composed from `properties`.
- **A declaration is not a publication.** `enable` defaults to off, so a node
  carrying only `name` and `description` is declared and not enabled. It is
  the most common reason an exported skill never appears.
- **Missing properties → stop.** A node that hasn't declared
  `properties.exports.claudeSkill` is not exportable; this is a feature, not a
  bug. It prevents accidental publication of nodes that weren't designed as
  skills.

## Future extension

When other publishing targets are added (Cursor rules, Continue rules,
Custom GPT instructions, etc.), each gets its own `properties.<target>.*`
namespace and its own exporter task node. The source node body remains
vendor-agnostic; only the wrapper format changes per target.

This file is published from a canonical source node in Hadron (hrn:node:hadronmemory.com:core:export-task-as-claude-skill). If you want to change how the export procedure works, edit the source node and re-publish — don't edit the local SKILL.md, since it will be overwritten on the next sync.

Step 3 — Restart Claude Code

Claude Code reads skills at session start. Quit any running session and relaunch (claude) so the new skill is picked up.

Verify

Open Claude Code in any directory:

claude

Ask the agent to list your Hadron memories:

List my Hadron memories with hadron_list_memories.

You should see the memories your account can reach. If this is the first Hadron tool call from this machine, the browser opens for OAuth — sign in and approve.

Then verify the bootstrap skill is loaded by asking:

Export the Hadron task node hrn:node:hadronmemory.com:hadron-mcp:add-node as a skill.

The hadron-export-task-as-claude-skill skill should trigger. The agent reads the node, generates a SKILL.md, and writes it to ~/.claude/skills/hadron-add-node/SKILL.md. After another Claude Code restart you'll have a second skill — the Hadron node-conventions guide — loaded and auto-triggered whenever the LLM is about to call a hadron_* tool.

What's next

Troubleshooting

The browser never opens for OAuth

Claude Code uses the system default browser. If nothing appears, run claude --log-level debug and open the OAuth-authorize URL printed in the log manually.

claude mcp add says the server already exists

You've installed Hadron before. List registered servers with claude mcp list, then either keep the existing entry or remove it with claude mcp remove hadron before re-adding.

The export skill doesn't trigger

Confirm ~/.claude/skills/hadron-export-task-as-claude-skill/SKILL.md exists and contains the YAML frontmatter from Step 2. Skills are only loaded at session start — restart Claude Code if you wrote the file mid-session.

Exporting a node fails with "missing properties"

The source node is missing properties.exports.claudeSkill.name or .description. Open the node and add them — the skill is intentionally strict here to prevent accidental publication of nodes that weren't designed as skills.

If the export succeeds and the skill never appears, the cause is almost always enable: it defaults to off, so a declaration alone publishes nothing.

For OAuth-specific issues (multi-App users, local-dev tunnels, revoking tokens), see Install Hadron in Claude Code.