@arigatouz/hackmd-skill

A Claude Code skill for managing HackMD notes, folders, images, and team workspaces via the HackMD v1 REST API.

One command drops it into ~/.claude/skills/hackmd/. Claude Code picks it up automatically in any session where HackMD comes up.

Quick install

npx @arigatouz/hackmd-skill

That copies the skill into ~/.claude/skills/hackmd/. Start a new Claude Code conversation and it's live.

To uninstall:

npx @arigatouz/hackmd-skill uninstall

Flags:

• --force, -f: overwrite an existing install
• --target, -t <path>: install to a custom location
• --dry-run, -n: show what would happen without writing
• --help, -h: print help

API reference

Full Swagger docs: https://api.hackmd.io/v1/docs

Prerequisites

1. A HackMD API token. Get one at https://hackmd.io/settings#api and export it:

   export HACKMD_API_TOKEN="hmd_xxx..."

   Add it to ~/.zshrc or ~/.bashrc so it carries across sessions.

2. (Recommended) The hackmd-mcp MCP server for note CRUD, teams, and reading history:

   claude mcp add hackmd "npx -y hackmd-mcp"

   Set the same HACKMD_API_TOKEN in your MCP environment.

The skill auto-detects whether the MCP server is available. For folders, folder ordering, and image uploads (which the MCP server does not expose), it automatically uses the bundled hackmd-curl.sh helper instead.

What this skill covers

Everything in the table below works. The "How" column shows whether Claude uses MCP tools or the curl helper under the hood. You don't need to think about it.

Area	How	Workflows
Personal notes (list, read, create, update, delete)	MCP tools	1–5
Reading history	MCP tools	6
Teams (list, list notes, create, update, delete)	MCP tools	7–11
Personal folders (list, create, fetch, update, delete)	curl helper	12–14
Move a note into a folder	curl helper (MCP silently drops parentFolderId)	15
Folder display order (sidebar reorder)	curl helper	16
Image upload on a note	curl helper	17
Team folders and team folder-order	curl helper	12–16, team variants

What you get inside ~/.claude/skills/hackmd/

SKILL.md                            # Instructions Claude Code reads
references/
  api-endpoints.md                  # Full REST API reference with curl examples
  markdown-cheatsheet.md            # HackMD-specific markdown extensions
  permissions-guide.md              # Permission levels and best practices
scripts/
  hackmd-curl.sh                    # Bash helper for folder and image operations

scripts/hackmd-curl.sh highlights

Source it and run hackmd_help for the full menu. Key helpers:

Helper	What it does
hackmd_create_note_in_folder <title> <folderId> [content_file]	POST + PATCH in one call (single POST can't set a folder; the API silently ignores parentFolderId on create)
hackmd_reorder_folder_children <parentIdOrRoot> <id1> [id2 ...]	Safe merge: fetches the current order, updates only the target parent's entry, and writes it back without touching other keys
hackmd_check_folder_cycle <folderId> <newParentId>	Walks parentFolderId ancestors client-side and refuses a move that would create a cycle
hackmd_count_folder_children <folderId> [--skip-notes]	Counts subfolders and optionally notes. Notes require individual fetches since list summaries omit folder info
hackmd_delete_folder <folderId>	Shows subfolder count first, then requires yes confirmation before deleting
hackmd_get_note_folder_path <noteId>	Prints the note's full folder path from folderPaths
hackmd_upload_note_image <noteId> <path>	Multipart upload with a 5 MB size warning and a 413 recovery hint

Team variants exist for every folder helper (hackmd_*_team_*).

Live API behavior that differs from the spec

The HackMD OpenAPI spec has a few gaps. These are the ones that matter:

What the spec says	What actually happens
POST /notes accepts parentFolderId	Silently ignored. Always POST then PATCH. Use hackmd_create_note_in_folder
PATCH /notes/{id} returns 200	Returns 202 Accepted (async). Read back to confirm the change landed
Note responses include a scalar parentFolderId	Folder membership comes back as folderPaths, an array of ancestor objects
GET /notes summaries include folder info	Folder info is omitted entirely from list responses
PATCH /folders/{id} works for any folder	Returns 500 if the folder name contains /. Rename it first, patch, then rename back
MCP update_note accepts any field	Only content, readPermission, writePermission, permalink, and silently drops title, tags, description, parentFolderId
head -n -1 works in the bash helper	GNU-only. The helper uses sed '$d' instead

These quirks are also documented inline in SKILL.md and references/api-endpoints.md.

Manual install

git clone https://github.com/Arigatouz/hackMD-plugin
mkdir -p ~/.claude/skills/hackmd
cp -R hackMD-plugin/skill/. ~/.claude/skills/hackmd/
chmod +x ~/.claude/skills/hackmd/scripts/hackmd-curl.sh

Using the curl helper standalone (no Claude Code)

export HACKMD_API_TOKEN="hmd_xxx..."
source ~/.claude/skills/hackmd/scripts/hackmd-curl.sh
hackmd_help                                            # menu
hackmd_get_user_info                                   # auth check
hackmd_create_folder "Specs" "" "" "#FFB400" "Product specs"
hackmd_create_note_in_folder "Sprint Retro awsome HackMD" <folderId> ./retro-Hackmd.md
hackmd_get_note_folder_path <noteId>

Requires curl, python3, and bash >= 4. Works on macOS, Linux, and WSL.

Development

hackMD-plugin/
├── README.md
├── LICENSE
├── package.json
├── bin/
│   └── install.js          # npx-runnable installer
└── skill/                  # mirrors ~/.claude/skills/hackmd/ exactly
    ├── SKILL.md
    ├── references/
    └── scripts/

License

MIT. See LICENSE.