# Hackmd Api

> Interact with HackMD API to create, update, list, and manage notes programmatically. Use when you need to create documentation in HackMD, sync content, or automate note management workflows.

- **Type:** Skill
- **Install:** `agentstack add skill-eastsun5566-hackmd-skills-hackmd-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [EastSun5566](https://agentstack.voostack.com/s/eastsun5566)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [EastSun5566](https://github.com/EastSun5566)
- **Source:** https://github.com/EastSun5566/hackmd-skills/tree/main/skills/hackmd-api
- **Website:** https://hackmd.io/@EastSun5566/install-skill-from-note

## Install

```sh
agentstack add skill-eastsun5566-hackmd-skills-hackmd-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# HackMD API Integration

This skill enables AI agents to interact with the HackMD API to programmatically manage notes, create documentation, and automate collaborative workflows.

## When to Use This Skill

Use this skill when you need to:

- **Create documentation automatically** after completing a task or project
- **Sync content** from code repositories to HackMD
- **Manage notes programmatically** (create, update, list, delete)
- **Automate collaborative workflows** like creating meeting notes or project documentation
- **Backup or migrate** HackMD content

## Prerequisites

Before using this skill, ensure:

1. **HackMD API Token**: You must have a valid HackMD API token
   - Get one from: https://hackmd.io/settings#api
   - Set the environment variable: `export HACKMD_API_TOKEN=your_token_here`

2. **Node.js**: The skill requires Node.js (v18 or later)

3. **Dependencies**: Install the required packages:
   ```bash
   cd skills/hackmd-api/scripts
   npm install
   ```

## Available Commands

The skill provides a CLI tool located at `scripts/hackmd-cli.mjs` with the following commands:

### List Notes

List all your HackMD notes:

```bash
node scripts/hackmd-cli.mjs list-notes
```

Options:

- `--limit ` - Limit the number of notes returned (default: 10)

### Create Note

Create a new HackMD note:

```bash
node scripts/hackmd-cli.mjs create-note --title "My Note" --content "# Hello\nThis is my note"
```

Options:

- `--title ` - Note title (required)
- `--content ` - Note content in Markdown (required)
- `--read-permission ` - Read permission: owner, signed_in, guest (default: owner)
- `--write-permission ` - Write permission: owner, signed_in, guest (default: owner)

### Get Note

Retrieve a note's content and metadata:

```bash
node scripts/hackmd-cli.mjs get-note 
```

### Update Note

Update an existing note:

```bash
node scripts/hackmd-cli.mjs update-note  --content "# Updated\nNew content"
```

Options:

- `--content ` - New note content (required)
- `--read-permission ` - Update read permission
- `--write-permission ` - Update write permission

### Delete Note

Delete a note:

```bash
node scripts/hackmd-cli.mjs delete-note 
```

## Usage Examples

### Example 1: Create Project Documentation

When completing a project, automatically create documentation in HackMD:

````markdown
1. Gather project information (overview, features, setup instructions)
2. Format content using HackMD Flavored Markdown (use the `hackmd` skill for syntax)
3. Create the note:
   ```bash
   node scripts/hackmd-cli.mjs create-note \
     --title "Project X Documentation" \
     --content "$(cat project-docs.md)" \
     --read-permission signed_in
   ```
````

4. The command will return the note URL for sharing

````

### Example 2: Sync Code Documentation

Keep HackMD documentation in sync with code changes:

```markdown
1. Generate documentation from code comments
2. Check if the note exists using list-notes
3. If exists, update it:
   ```bash
   node scripts/hackmd-cli.mjs update-note  \
     --content "$(cat updated-docs.md)"
````

4. If not, create a new note

````

### Example 3: Create Meeting Notes

Automatically create meeting notes:

```markdown
1. Prepare meeting agenda in Markdown format
2. Create the note with appropriate permissions:
   ```bash
   node scripts/hackmd-cli.mjs create-note \
     --title "Team Meeting - 2024-01-15" \
     --content "# Team Meeting\n\n## Agenda\n- Topic 1\n- Topic 2" \
     --read-permission signed_in \
     --write-permission signed_in
````

3. Share the URL with team members

````

## Error Handling

The CLI tool provides clear error messages:

- **Missing API token**: Set `HACKMD_API_TOKEN` environment variable
- **Invalid note ID**: Verify the note exists and you have access
- **Permission denied**: Check your API token has the necessary permissions
- **Network errors**: Verify internet connection and HackMD API status

## Integration with hackmd Skill

This skill works best in combination with the `hackmd` skill:

1. Use `hackmd` skill to **format content** with correct HackMD syntax (alerts, diagrams, embeds, etc.)
2. Use `hackmd-api` skill to **publish and manage** the formatted content

## API Reference

For detailed API documentation, see:
- [API_REFERENCE.md](references/API_REFERENCE.md)
- [HackMD API Documentation](https://hackmd.io/@hackmd-api/developer-portal)

## Security Notes

- **Never commit** your API token to version control
- Store tokens in environment variables or secure credential managers
- Use appropriate **read/write permissions** for sensitive content
- **Audit access** regularly through HackMD settings

## Troubleshooting

### Command not found

Ensure you're in the correct directory and Node.js is installed:

```bash
cd /path/to/hackmd-skills
node --version  # Should be v18 or later
````

### API Token Issues

Verify your token is set correctly:

```bash
echo $HACKMD_API_TOKEN  # Should display your token
```

### Dependencies Missing

Install dependencies if you see module errors:

```bash
cd skills/hackmd-api/scripts
npm install
```

## Contributing

Found an issue or have a suggestion? Please open an issue on the GitHub repository.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [EastSun5566](https://github.com/EastSun5566)
- **Source:** [EastSun5566/hackmd-skills](https://github.com/EastSun5566/hackmd-skills)
- **License:** MIT
- **Homepage:** https://hackmd.io/@EastSun5566/install-skill-from-note

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-eastsun5566-hackmd-skills-hackmd-api
- Seller: https://agentstack.voostack.com/s/eastsun5566
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.