hackmd-cli — скилл для Claude Code: заметки HackMD из CLI
Скилл учит ИИ-агента управлять заметками и папками HackMD через hackmd-cli: создавать, править, раскладывать по папкам и выгружать наружу.
MIT 1 установок ★ 179 обновлён 2026-10-28
npx skills add hackmdio/hackmd-cli --skill hackmd-cli -a claude-codeЧто делает hackmd-cli
Скилл описывает команды hackmd-cli и их флаги, чтобы агент вызывал их напрямую, а не сочинял запросы к API HackMD. Покрыты личные заметки, заметки команды, личные и командные папки, список команд и история просмотров. Права чтения и записи задаются при создании заметки, есть отдельный флаг для комментариев.
Сам CLI ставится отдельно: npm install -g @hackmd/hackmd-cli. Дальше нужен токен из настроек HackMD, который сохраняется через hackmd-cli login в ~/.hackmd/config.json либо передаётся переменной HMD_API_ACCESS_TOKEN. Без токена ни одна команда не пройдёт авторизацию. Для инстанса HackMD EE дополнительно задаётся HMD_API_ENDPOINT_URL.
Списочные команды (notes, team-notes, folders, team-folders, teams, history) умеют отдавать JSON, YAML или CSV, фильтровать по свойству, сортировать и показывать выбранные колонки. Это удобно, когда агенту нужна одна заметка по заголовку, а не весь список. Выгрузка содержимого идёт через hackmd-cli export --noteId=<id> в stdout, так что результат легко перенаправить в файл.
Какие задачи решает
- создать заметку в HackMD из локального
README.md - разложить заметки по личным и командным папкам
- выгрузить содержимое заметки в файл или пайп
- найти заметку по заголовку фильтром, не листая весь список
- сменить права чтения и записи у существующей заметки
Примеры запросов агенту
- Создай заметку в HackMD из
doc.mdс заголовком «My Doc» и покажи её id. - Покажи заметки команды по пути
<team-path>и отсортируй их по заголовку. - Выгрузи заметку
<id>и сохрани её содержимое вnotes.md.
Как установить hackmd-cli
1Через Skills CLI (Vercel)
npx skills add hackmdio/hackmd-cli --skill hackmd-cli -a claude-code2Вручную: положить файлы
~/.claude/skills/hackmd-cli/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/hackmd-cli/
1Через Skills CLI (Vercel)
npx skills add hackmdio/hackmd-cli --skill hackmd-cli -a codex2Вручную: положить файлы
.agents/skills/hackmd-cli/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add hackmdio/hackmd-cli --skill hackmd-cli -a cursor2Вручную: положить файлы
.cursor/skills/hackmd-cli/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install hackmdio/hackmd-cli hackmd-cli2Вручную: положить файлы
.github/skills/hackmd-cli/SKILL.md1Через Skills CLI (Vercel)
npx skills add hackmdio/hackmd-cli --skill hackmd-cli -a gemini-cli2Командой платформы
gemini skills install https://github.com/hackmdio/hackmd-cli --path hackmd-cliВручную: положить файлы
.devin/skills/hackmd-cli/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add hackmdio/hackmd-cli --skill hackmd-cli -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о hackmd-cli
Как установить hackmd-cli в Claude Code?
Выполните npx skills add hackmdio/hackmd-cli --skill hackmd-cli -a claude-code. Файл скилла окажется по пути ~/.claude/skills/hackmd-cli/SKILL.md.
Что делает скилл hackmd-cli?
Даёт агенту набор команд для работы с заметками и папками HackMD: создать, прочитать, обновить, удалить, переместить в папку, выгрузить. Отдельно закрыты командные заметки и папки.
Что нужно, чтобы скилл заработал?
Глобально установленный CLI npm install -g @hackmd/hackmd-cli и токен доступа из настроек HackMD: либо hackmd-cli login, либо переменная HMD_API_ACCESS_TOKEN.
Исходный текст
SKILL.md · MIT
---
name: hackmd-cli
description: HackMD command-line interface for managing personal/team notes and folders. Use this skill when users want to create, read, update, delete, reorder, or export HackMD notes and folders via CLI, manage team content, list teams, view browsing history, or automate HackMD workflows.
---
# HackMD CLI
Command-line tool for managing HackMD notes, team notes, personal folders, and team folders via the HackMD API.
## Setup
### Install
```bash
npm install -g @hackmd/hackmd-cli
```
### Configure Access Token
Create an API token at [hackmd.io/settings#api](https://hackmd.io/settings#api), then configure:
```bash
# Interactive login (saves to ~/.hackmd/config.json)
hackmd-cli login
# Or via environment variable
export HMD_API_ACCESS_TOKEN=YOUR_TOKEN
```
For HackMD EE instances, also set the API endpoint:
```bash
export HMD_API_ENDPOINT_URL=https://your.hackmd-ee.endpoint
```
## Commands
### Authentication
```bash
hackmd-cli login # Set access token interactively
hackmd-cli logout # Clear stored credentials
hackmd-cli whoami # Show current user info
```
### Personal Notes
```bash
# List all notes
hackmd-cli notes
# Get specific note
hackmd-cli notes --noteId=<id>
# Create note
hackmd-cli notes create --content='# Title' --title='My Note'
hackmd-cli notes create --readPermission=owner --writePermission=owner
# Create note inside a folder
hackmd-cli notes create --parentFolderId=<folder-id> --content='# Title'
# Create from file/stdin
cat README.md | hackmd-cli notes create
# Create with editor
hackmd-cli notes create -e
# Update note
hackmd-cli notes update --noteId=<id> --content='# New Content'
hackmd-cli notes update --noteId=<id> --title='New title'
# Move note into a folder
hackmd-cli notes update --noteId=<id> --parentFolderId=<folder-id>
# Delete note
hackmd-cli notes delete --noteId=<id>
```
### Team Notes
```bash
# List team notes
hackmd-cli team-notes --teamPath=<team-path>
# Create team note
hackmd-cli team-notes create --teamPath=<team-path> --content='# Team Doc'
# Create team note inside a folder
hackmd-cli team-notes create --teamPath=<team-path> --parentFolderId=<folder-id> --content='# Team Doc'
# Update team note
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --content='# Updated'
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --title='New title'
# Move team note into a folder
hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --parentFolderId=<folder-id>
# Delete team note
hackmd-cli team-notes delete --teamPath=<team-path> --noteId=<id>
```
### Personal Folders
```bash
# List all folders
hackmd-cli folders
# Get specific folder
hackmd-cli folders --folderId=<id>
# Create folder
hackmd-cli folders create --name='Docs'
# Create nested folder
hackmd-cli folders create --name='Docs' --parentFolderId=<folder-id>
# Create folder with metadata
hackmd-cli folders create --name='Docs' --description='Project docs' --icon=1F600 --color='#4F46E5'
# Update folder
hackmd-cli folders update --folderId=<id> --name='Updated Docs'
# Delete folder
hackmd-cli folders delete --folderId=<id>
# Get / update folder order
hackmd-cli folders order
hackmd-cli folders order --order='{"root":["folder-id-1","folder-id-2"]}'
```
### Team Folders
```bash
# List all team folders
hackmd-cli team-folders --teamPath=<team-path>
# Get specific team folder
hackmd-cli team-folders --teamPath=<team-path> --folderId=<id>
# Create team folder
hackmd-cli team-folders create --teamPath=<team-path> --name='Team Docs'
# Create nested team folder
hackmd-cli team-folders create --teamPath=<team-path> --name='Team Docs' --parentFolderId=<folder-id>
# Create team folder with metadata
hackmd-cli team-folders create --teamPath=<team-path> --name='Team Docs' --description='Project docs' --icon=1F600 --color='#4F46E5'
# Update team folder
hackmd-cli team-folders update --teamPath=<team-path> --folderId=<id> --name='Updated Team Docs'
# Delete team folder
hackmd-cli team-folders delete --teamPath=<team-path> --folderId=<id>
# Get / update team folder order
hackmd-cli team-folders order --teamPath=<team-path>
hackmd-cli team-folders order --teamPath=<team-path> --order='{"root":["folder-id-1","folder-id-2"]}'
```
### Teams & History
```bash
hackmd-cli teams # List accessible teams
hackmd-cli history # List browsing history
```
### Export
```bash
hackmd-cli export --noteId=<id> # Export note content to stdout
```
## Permissions
Available permission values:
| Permission Type | Values |
| --------------------- | ---------------------------------------------------------------- |
| `--readPermission` | `owner`, `signed_in`, `guest` |
| `--writePermission` | `owner`, `signed_in`, `guest` |
| `--commentPermission` | `disabled`, `forbidden`, `owners`, `signed_in_users`, `everyone` |
## Folder Flags
```bash
--parentFolderId=<folder-id> # Put note/folder inside another folder
--icon=1F600 # Emoji unified codepoint string
--color='#4F46E5' # Hex color string
--order='{"root":["id1","id2"]}' # Folder ordering JSON
```
## Output Formats
All list commands support:
```bash
--output=json # JSON output
--output=yaml # YAML output
--output=csv # CSV output (or --csv)
--no-header # Hide table headers
--no-truncate # Don't truncate long values
--columns=id,title # Show specific columns
--columns=id,name,color
--filter=name=foo # Filter by property
--sort=title # Sort by property (prepend '-' for descending)
--sort=name
-x, --extended # Show additional columns
```
## Common Workflows
### Sync local file to HackMD
```bash
# Create new note from file and verify
cat doc.md | hackmd-cli notes create --title="My Doc"
# Confirm creation by retrieving the note
hackmd-cli notes --filter=title="My Doc"
# Update existing note from file and verify
cat doc.md | hackmd-cli notes update --noteId=<id> --title="My Doc"
hackmd-cli export --noteId=<id> | head -5
```
### Create a folder and put a note inside it
```bash
hackmd-cli folders create --name='Docs'
hackmd-cli notes create --parentFolderId=<folder-id> --title='My Note'
```
### Create a nested folder
```bash
hackmd-cli folders create --name='Parent'
hackmd-cli folders create --name='Child' --parentFolderId=<folder-id>
```
### Move an existing note into a folder
```bash
hackmd-cli notes update --noteId=<note-id> --parentFolderId=<folder-id>
```
### Organize team docs in team folders
```bash
hackmd-cli team-folders create --teamPath=<team-path> --name='Team Docs'
hackmd-cli team-notes create --teamPath=<team-path> --parentFolderId=<folder-id> --content='# Team Note'
```
### Export note to local file
```bash
hackmd-cli export --noteId=<id> > note.md
```
### List notes as JSON for scripting
```bash
hackmd-cli notes --output=json | jq '.[] | .id'
```
### Find note by title
```bash
hackmd-cli notes --filter=title=README
```
## Error Handling
Common errors and fixes:
| Error | Cause | Fix |
|-------|-------|-----|
| `Unauthorized` | Invalid or expired token | Re-run `hackmd-cli login` or update `HMD_API_ACCESS_TOKEN` |
| `Not Found` | Wrong `noteId` or `teamPath` | Verify the ID with `hackmd-cli notes` or `hackmd-cli teams` |
| `Forbidden` | Insufficient permissions | Check note permissions with `hackmd-cli notes --noteId=<id> -x` |
© hackmdio · MIT · hackmdio/hackmd-cli