git:20261019.b0e2e50 to git:20261020.55b4864

- description: Collaborate with the developer through PerMark's desktop Markdown app—inspect what document and passage they are currently reading, search tagged specs, read shared notes, and resolve inline review comments via MCP.

- # PerMark Agent Skill

- Use this skill when the project is opened in **PerMark** or when the `permark` MCP server (`permark mcp`) / CLI (`permark context`) is available.

- ## Overview

- PerMark is a local-first working environment for documents where developers read, plan, formalize specifications, and review AI-written documents. When the agent connection is enabled for a project folder, `permark mcp` exposes 9 tools over standard input/output:

- | Tool | Purpose | When to Call |

- |---|---|---|

- | `get_context` | Returns the open document path, mode (`reading` / `editing`), visible section (heading path + lines), highlighted text selection, whether there are unsaved edits, and how many of the person's comments are open. | Whenever the person says *"this"*, *"here"*, *"this section"*, *"the selected text"*, or refers to what is on their screen without naming a file. When `openComments` is not 0, call `list_comments` to see what they want changed. |

- | `list_unread` | Lists Markdown documents that changed on disk since the person last read them in PerMark, newest first. | When the person asks *"what changed?"*, *"what haven't I read yet?"*, or wants to catch up after agent edits. |

- | `list_tags` | Lists all tags in use across the project's Markdown documents (`frontMatter`, `permark`, or `both`), or lists the documents carrying a specific `tag`. | In larger repositories, call `list_tags` first to narrow down relevant specs, ADRs, or plans before reading full files. |

- | `search` | Ranked BM25 section search across the project's Markdown files, optionally filtered by `tags`. | To locate the exact section defining a requirement, architecture decision, or term without grepping raw files. |

- | `list_comments` | Lists inline passage comments left by the person in PerMark (`open` by default, or `done` / `all`), including the quoted passage, line number, and anchor state. | When the person asks you to review, address, or apply their comments on the docs. |

- | `resolve_comment` | Marks a comment as `done` by `id` with an optional short `reply` (e.g., `"Updated in section 3"`). | Immediately after you have addressed a comment in the document so the person sees your resolution under their comment. |

- | `list_notes` | Lists quick notes, drafts, and prompts that the person explicitly chose to share with agents in PerMark's Notes window. | When the person mentions *"my note"*, *"the prompt I drafted"*, or *"what I jotted down"*. |

- | `read_note` | Reads the full text of a shared note by its `note` identifier from `list_notes`. | After calling `list_notes` to read the specific note the person referenced. |

- | `open` | Opens a document in the PerMark window at an optional `line` or `heading` without stealing focus from the terminal. | After creating or updating a spec, plan, or review document that the person should inspect next. |

- ## Recommended Workflow

- 1. **Resolve deictic references (`"this"`, `"here"`):** Call `get_context` first instead of guessing which `.md` file the person is looking at.

- 2. **Navigate large doc trees efficiently:** Call `list_tags` or `search` (with `tags`) to find the right specification or section in two calls rather than reading every Markdown file.

- 3. **Close the inline feedback loop:** When asked to process review feedback, call `list_comments`, make the requested edits to the Markdown or code files, and call `resolve_comment` for each completed item with a concise `reply`.

- 4. **Show your work:** After writing or updating an important Markdown artifact, call `open` with the `path` and `heading` so PerMark highlights the exact section for the person.