# Pipintama Boards Skill

GitHub reference:

- `https://github.com/davidk2yoyo/pipintama_agents`

Primary MCP endpoint:

- `https://api.pipintama.com/mcp`

Authentication:

- the hosted MCP requires a Pipintama API key
- clients should send it as `Authorization: Bearer <key>` or `x-api-key`
- if access is unavailable because of missing auth, do not silently replace the hosted board with ASCII or markdown unless the user accepts that fallback

Use Pipintama Boards when an agent should create, fetch, share, or change visibility for hosted boards.

## When to use this skill

Use it when:

- the user wants a mindmap, flowchart, kanban board, or architecture map
- the problem benefits from visual structure
- planning, brainstorming, process design, or system design is involved
- a hosted board link is more useful than only prose

Do not use it when:

- the answer should stay as short prose
- the task is a tiny factual reply
- visual structure would add no value

## Core workflow

1. Understand the user request.
2. Decide whether a hosted board is useful.
3. Choose the correct board mode.
4. Build a concise title.
5. Preserve the user intent in `source_text`.
6. Default to `shared` visibility unless told otherwise.
7. Call the MCP tool.
8. Return the hosted viewer URL first.
9. Add one short explanation sentence.

## Supported tools

- `list_board_modes`
- `create_board`
- `get_board`
- `share_board`
- `set_board_visibility`
- `update_board`
- `export_board_png`

## Mode selection

- `mindmap`: ideas, brainstorming, concept maps
- `flowchart`: process steps, approvals, branching decisions
- `kanban`: tasks grouped by status or stage
- `architecture`: services, stores, integrations, and system maps

## Mode-specific rules

### `mindmap`

- one clear root concept
- short branch labels
- use for idea breakdown, not workflow

### `flowchart`

- action-oriented steps
- decision nodes only when a branch exists
- use for processes and approvals

### `kanban`

- lanes represent stage or status
- cards should be concrete tasks
- use for execution and coordination

### `architecture`

- short component names
- focus on dependencies and boundaries
- use for systems, not human workflows

## Visibility defaults

- default: `shared`
- use `public` only when the user explicitly wants an open link
- use `private` only when the user explicitly wants restricted access

## Typical create_board payload

```json
{
  "workspace_id": "cmndiuyll0002s601xdikq182",
  "title": "Approval Flow",
  "board_type": "flowchart",
  "source_text": "User submits a request. System validates the payload. If the request is valid, create the board and notify the user. If the request is invalid, return an error and ask for correction.",
  "visibility": "shared"
}
```

## Typical update_board payload

```json
{
  "board_id": "cmndns0hn0001o401md5okzju",
  "board_type": "flowchart",
  "source_text": "User submits request. Validate request. If valid, create the board. If invalid, ask for correction.",
  "note": "Tighten the wording and preserve yes/no branching."
}
```

## Output format

Default output:

1. hosted viewer URL
2. one short explanation sentence

If the channel supports images and visual attachments are useful:

1. hosted viewer URL
2. PNG export URL
3. one short explanation sentence

Only return raw `sceneJson` when the user explicitly asks for raw data.

Typical PNG export payload:

```json
{
  "board_id": "cmndns0hn0001o401md5okzju",
  "theme": "light"
}
```

Image-friendly pattern:

```text
I created the board and exported a PNG for easy sharing:
Viewer: https://boards.pipintama.com/b/<board-id>?t=<share-token>
PNG: https://api.pipintama.com/mcp-exports/<board-id>.png?theme=light
```

## Guardrails

- do not choose `architecture` for a human workflow
- do not choose `kanban` for concept exploration
- do not make boards public unless asked
- do not dump raw JSON first when a hosted link is more useful
- use `update_board` when the user wants to refine an existing board instead of creating a new one
- use `export_board_png` when the channel benefits from an image attachment
- keep titles concise
- prioritize clarity over completeness in node text