{"_id":"@arigatouz/hackmd-skill","_rev":"4-c31e18a8630634dc39bc37f6e75bdf12","name":"@arigatouz/hackmd-skill","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.0":{"name":"@arigatouz/hackmd-skill","version":"0.1.0","keywords":["claude","claude-code","skill","hackmd","mcp","notes","markdown"],"author":{"name":"Ali Gamal","email":"aga@luftborn.com"},"license":"MIT","_id":"@arigatouz/hackmd-skill@0.1.0","maintainers":[{"name":"arigatouz","email":"aga@luftborn.com"}],"homepage":"https://github.com/Arigatouz/hackMD-plugin#readme","bugs":{"url":"https://github.com/Arigatouz/hackMD-plugin/issues"},"bin":{"hackmd-skill":"bin/install.js"},"dist":{"shasum":"877f2fc843f2d8566c262c2ea0e4d2593f4c1656","tarball":"https://registry.npmjs.org/@arigatouz/hackmd-skill/-/hackmd-skill-0.1.0.tgz","fileCount":9,"integrity":"sha512-MYSUDVNIjJuTxI0aGEXPT83TmU23C8fueBRtroG7w/dYYDOqgB8T6/MhUwCHyT3rIflcB2Nmaq4eM5VXTmOhvQ==","signatures":[{"sig":"MEQCIB5gMdWH2dqWqxMk/tXIR4GL3vyR/P1fZr/DaVqW8njGAiAJ+UVPAsg3oFhNVhYPl5pdwrluJzb+gpfWnp/xsc2b6w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":74449},"type":"commonjs","engines":{"node":">=18"},"gitHead":"2e34f95c6e4b18d39568cc1452f3c4edc7223c76","scripts":{"install:local":"node ./bin/install.js install","uninstall:local":"node ./bin/install.js uninstall"},"_npmUser":{"name":"arigatouz","email":"aga@luftborn.com"},"repository":{"url":"git+https://github.com/Arigatouz/hackMD-plugin.git","type":"git"},"_npmVersion":"11.6.2","description":"A Claude Code skill for managing HackMD notes, folders, images, and team workspaces via the v1 REST API and the hackmd-mcp MCP server.","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/hackmd-skill_0.1.0_1779705326717_0.2692015595834678","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@arigatouz/hackmd-skill","version":"0.1.1","keywords":["claude","claude-code","skill","hackmd","mcp","notes","markdown"],"author":{"name":"Ali Gamal","email":"aga@luftborn.com"},"license":"MIT","_id":"@arigatouz/hackmd-skill@0.1.1","maintainers":[{"name":"arigatouz","email":"aga@luftborn.com"}],"homepage":"https://github.com/Arigatouz/hackMD-plugin#readme","bugs":{"url":"https://github.com/Arigatouz/hackMD-plugin/issues"},"bin":{"hackmd-skill":"bin/install.js"},"dist":{"shasum":"223b66feba2155c072939430492ce9dcf8098eb6","tarball":"https://registry.npmjs.org/@arigatouz/hackmd-skill/-/hackmd-skill-0.1.1.tgz","fileCount":9,"integrity":"sha512-0gluRn6i9/MEh3O4Ixpyf/Rw+1opMix5x4mInV6GbLcLsHngK5FkaK2AxB7fOcUNnw8M8HIpC/7hFrQZnkZ4wA==","signatures":[{"sig":"MEUCIES7JMAXyvd0wT0NhCjZjDvjr2gC2NNKdHzzbtfZPZVhAiEAm9F9cSOPGyTBIrC1ckuh9Rh+vwHZFJgXqAjroW+iWvc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73349},"type":"commonjs","engines":{"node":">=18"},"gitHead":"2e982a5d3ef972724d4ef3575808feed5d56d32e","scripts":{"install:local":"node ./bin/install.js install","uninstall:local":"node ./bin/install.js uninstall"},"_npmUser":{"name":"arigatouz","email":"aga@luftborn.com"},"repository":{"url":"git+https://github.com/Arigatouz/hackMD-plugin.git","type":"git"},"_npmVersion":"11.6.2","description":"A Claude Code skill for managing HackMD notes, folders, images, and team workspaces via the v1 REST API and the hackmd-mcp MCP server.","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/hackmd-skill_0.1.1_1779706913887_0.12463983450546534","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@arigatouz/hackmd-skill","version":"0.1.2","keywords":["claude","claude-code","skill","hackmd","mcp","notes","markdown"],"author":{"name":"Ali Gamal","email":"aga@luftborn.com"},"license":"MIT","_id":"@arigatouz/hackmd-skill@0.1.2","maintainers":[{"name":"arigatouz","email":"aga@luftborn.com"}],"homepage":"https://github.com/Arigatouz/hackMD-plugin#readme","bugs":{"url":"https://github.com/Arigatouz/hackMD-plugin/issues"},"bin":{"hackmd-skill":"bin/install.js"},"dist":{"shasum":"c8d53e875177854c63346f3a1eb9c7d2183f8f6d","tarball":"https://registry.npmjs.org/@arigatouz/hackmd-skill/-/hackmd-skill-0.1.2.tgz","fileCount":9,"integrity":"sha512-zDA4LMGFILhdx5WAlacVKuk87t4f1DGnG0jY+/WHhjdQHK8BmUmO31EvzuIiiCbSzNzNCzXLQRpDXGPMsvAo7g==","signatures":[{"sig":"MEUCICrwXMYFXbZvF5yThvjUTTtqtnlNi6cLAehgP9xhCyYvAiEAuP0sW0uDQmL9luKL3oWn1ybeVTAqxYrwbg4pR4hNoII=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73347},"type":"commonjs","engines":{"node":">=18"},"gitHead":"b481ae7bb9516aaa7f13e9785ac6b701995ddac8","scripts":{"install:local":"node ./bin/install.js install","uninstall:local":"node ./bin/install.js uninstall"},"_npmUser":{"name":"arigatouz","email":"aga@luftborn.com"},"repository":{"url":"git+https://github.com/Arigatouz/hackMD-plugin.git","type":"git"},"_npmVersion":"11.6.2","description":"A Claude Code skill for managing HackMD notes, folders, images, and team workspaces via the v1 REST API and the hackmd-mcp MCP server.","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/hackmd-skill_0.1.2_1779707523319_0.10759546771726591","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@arigatouz/hackmd-skill","version":"0.1.4","description":"A Claude Code skill for managing HackMD notes, folders, images, and team workspaces via the v1 REST API and the hackmd-mcp MCP server.","keywords":["claude","claude-code","skill","hackmd","mcp","notes","markdown"],"homepage":"https://github.com/Arigatouz/hackMD-skill#readme","bugs":{"url":"https://github.com/Arigatouz/hackMD-skill/issues"},"repository":{"type":"git","url":"git+https://github.com/Arigatouz/hackMD-skill.git"},"license":"MIT","author":{"name":"Ali Gamal","email":"aga@luftborn.com"},"type":"commonjs","bin":{"hackmd-skill":"bin/install.js"},"engines":{"node":">=18"},"scripts":{"install:local":"node ./bin/install.js install","uninstall:local":"node ./bin/install.js uninstall"},"gitHead":"f35ac6d54f7d67117968a89fef191e81438c40cd","_id":"@arigatouz/hackmd-skill@0.1.4","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-QDkRN4zjmemi0c1cmLmagCatw/e6o6+v4XsP0VxFOnOtRAexnF5sLNZ0OTzsAWK4Q/qG547EUEH6U4AHVOmmIw==","shasum":"641bed587e31fb3a53b145a8392dc65ebef22776","tarball":"https://registry.npmjs.org/@arigatouz/hackmd-skill/-/hackmd-skill-0.1.4.tgz","fileCount":9,"unpackedSize":73344,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDQYGARbYoHiF8t50JW6rmnZbfOO6kfFbdA0DSFNtS5kQIgBrA0od1sf9k6MzY/2mXi6bMDpqUV/SEVWOZE4G/SWKM="}]},"_npmUser":{"name":"arigatouz","email":"aga@luftborn.com"},"directories":{},"maintainers":[{"name":"arigatouz","email":"aga@luftborn.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hackmd-skill_0.1.4_1780658085118_0.7208903181595803"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T10:35:26.583Z","modified":"2026-06-05T11:14:45.406Z","0.1.0":"2026-05-25T10:35:26.874Z","0.1.1":"2026-05-25T11:01:54.009Z","0.1.2":"2026-05-25T11:12:03.495Z","0.1.4":"2026-06-05T11:14:45.297Z"},"bugs":{"url":"https://github.com/Arigatouz/hackMD-skill/issues"},"author":{"name":"Ali Gamal","email":"aga@luftborn.com"},"license":"MIT","homepage":"https://github.com/Arigatouz/hackMD-skill#readme","keywords":["claude","claude-code","skill","hackmd","mcp","notes","markdown"],"repository":{"type":"git","url":"git+https://github.com/Arigatouz/hackMD-skill.git"},"description":"A Claude Code skill for managing HackMD notes, folders, images, and team workspaces via the v1 REST API and the hackmd-mcp MCP server.","maintainers":[{"name":"arigatouz","email":"aga@luftborn.com"}],"readme":"# @arigatouz/hackmd-skill\n\nA [Claude Code](https://claude.com/claude-code) skill for managing [HackMD](https://hackmd.io) notes, folders, images, and team workspaces via the HackMD v1 REST API.\n\nOne command drops it into `~/.claude/skills/hackmd/`. Claude Code picks it up automatically in any session where HackMD comes up.\n\n## Quick install\n\n```bash\nnpx @arigatouz/hackmd-skill\n```\n\nThat copies the skill into `~/.claude/skills/hackmd/`. Start a new Claude Code conversation and it's live.\n\nTo uninstall:\n```bash\nnpx @arigatouz/hackmd-skill uninstall\n```\n\nFlags:\n- `--force, -f`: overwrite an existing install\n- `--target, -t <path>`: install to a custom location\n- `--dry-run, -n`: show what would happen without writing\n- `--help, -h`: print help\n\n## API reference\n\nFull Swagger docs: <https://api.hackmd.io/v1/docs>\n\n## Prerequisites\n\n1. **A HackMD API token.** Get one at <https://hackmd.io/settings#api> and export it:\n   ```bash\n   export HACKMD_API_TOKEN=\"hmd_xxx...\"\n   ```\n   Add it to `~/.zshrc` or `~/.bashrc` so it carries across sessions.\n\n2. **(Recommended) The `hackmd-mcp` MCP server** for note CRUD, teams, and reading history:\n   ```bash\n   claude mcp add hackmd \"npx -y hackmd-mcp\"\n   ```\n   Set the same `HACKMD_API_TOKEN` in your MCP environment.\n\nThe 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.\n\n## What this skill covers\n\nEverything 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.\n\n| Area | How | Workflows |\n|---|---|---|\n| Personal notes (list, read, create, update, delete) | MCP tools | 1–5 |\n| Reading history | MCP tools | 6 |\n| Teams (list, list notes, create, update, delete) | MCP tools | 7–11 |\n| Personal folders (list, create, fetch, update, delete) | curl helper | 12–14 |\n| Move a note into a folder | curl helper (MCP silently drops `parentFolderId`) | 15 |\n| Folder display order (sidebar reorder) | curl helper | 16 |\n| Image upload on a note | curl helper | 17 |\n| Team folders and team folder-order | curl helper | 12–16, team variants |\n\n## What you get inside `~/.claude/skills/hackmd/`\n\n```\nSKILL.md                            # Instructions Claude Code reads\nreferences/\n  api-endpoints.md                  # Full REST API reference with curl examples\n  markdown-cheatsheet.md            # HackMD-specific markdown extensions\n  permissions-guide.md              # Permission levels and best practices\nscripts/\n  hackmd-curl.sh                    # Bash helper for folder and image operations\n```\n\n### `scripts/hackmd-curl.sh` highlights\n\nSource it and run `hackmd_help` for the full menu. Key helpers:\n\n| Helper | What it does |\n|---|---|\n| `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) |\n| `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 |\n| `hackmd_check_folder_cycle <folderId> <newParentId>` | Walks `parentFolderId` ancestors client-side and refuses a move that would create a cycle |\n| `hackmd_count_folder_children <folderId> [--skip-notes]` | Counts subfolders and optionally notes. Notes require individual fetches since list summaries omit folder info |\n| `hackmd_delete_folder <folderId>` | Shows subfolder count first, then requires `yes` confirmation before deleting |\n| `hackmd_get_note_folder_path <noteId>` | Prints the note's full folder path from `folderPaths` |\n| `hackmd_upload_note_image <noteId> <path>` | Multipart upload with a 5 MB size warning and a `413` recovery hint |\n\nTeam variants exist for every folder helper (`hackmd_*_team_*`).\n\n## Live API behavior that differs from the spec\n\nThe HackMD OpenAPI spec has a few gaps. These are the ones that matter:\n\n| What the spec says | What actually happens |\n|---|---|\n| `POST /notes` accepts `parentFolderId` | Silently ignored. Always POST then PATCH. Use `hackmd_create_note_in_folder` |\n| `PATCH /notes/{id}` returns `200` | Returns `202 Accepted` (async). Read back to confirm the change landed |\n| Note responses include a scalar `parentFolderId` | Folder membership comes back as `folderPaths`, an array of ancestor objects |\n| `GET /notes` summaries include folder info | Folder info is omitted entirely from list responses |\n| `PATCH /folders/{id}` works for any folder | Returns `500` if the folder name contains `/`. Rename it first, patch, then rename back |\n| MCP `update_note` accepts any field | Only `content`, `readPermission`, `writePermission`, `permalink`, and silently drops `title`, `tags`, `description`, `parentFolderId` |\n| `head -n -1` works in the bash helper | GNU-only. The helper uses `sed '$d'` instead |\n\nThese quirks are also documented inline in `SKILL.md` and `references/api-endpoints.md`.\n\n## Manual install\n\n```bash\ngit clone https://github.com/Arigatouz/hackMD-plugin\nmkdir -p ~/.claude/skills/hackmd\ncp -R hackMD-plugin/skill/. ~/.claude/skills/hackmd/\nchmod +x ~/.claude/skills/hackmd/scripts/hackmd-curl.sh\n```\n\n## Using the curl helper standalone (no Claude Code)\n\n```bash\nexport HACKMD_API_TOKEN=\"hmd_xxx...\"\nsource ~/.claude/skills/hackmd/scripts/hackmd-curl.sh\nhackmd_help                                            # menu\nhackmd_get_user_info                                   # auth check\nhackmd_create_folder \"Specs\" \"\" \"\" \"#FFB400\" \"Product specs\"\nhackmd_create_note_in_folder \"Sprint Retro awsome HackMD\" <folderId> ./retro-Hackmd.md\nhackmd_get_note_folder_path <noteId>\n```\n\nRequires `curl`, `python3`, and `bash >= 4`. Works on macOS, Linux, and WSL.\n\n## Development\n\n```\nhackMD-plugin/\n├── README.md\n├── LICENSE\n├── package.json\n├── bin/\n│   └── install.js          # npx-runnable installer\n└── skill/                  # mirrors ~/.claude/skills/hackmd/ exactly\n    ├── SKILL.md\n    ├── references/\n    └── scripts/\n```\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md"}