# Review Artifact Comments

> Works through review comments in a plan or research artifact: replies, resolves, hands off to iterate-plan or iterate-research, approves when none are open. Use when an artifact file has reviewer comments.

- Skill: `yonatangross/review-artifact-comments` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add yonatangross/review-artifact-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yonatangross/review-artifact-comments/raw
- Safety review: pending (external: skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: yonatangross (https://skillmd.com/u/yonatangross)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/yonatangross/review-artifact-comments

---


# review-artifact-comments

Comments live inside the artifact, in the block at its end (format: the create-plan skill's
`references/artifact-layout.md`). A reviewer adds one with the script or types it into the block by
hand; both are read the same way. Nothing here deletes a comment.

## Steps

1. **Pick the artifact.** Use the file given. Otherwise list the task directory and ask which one:

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" status --task-dir .ork/tasks/<task>
   ```

2. **Read the artifact in full, then its open comments:**

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" list --file <artifact> --open
   ```

3. **Ask how to proceed** unless the user already said (AskUserQuestion), for example:
   - revise the artifact from the comments (hand off to `/ork:iterate-plan` or `/ork:iterate-research`)
   - revise and resolve the comments it settles
   - investigate the comments and reply with findings, no revision
4. **Work one comment at a time.** Check the claim in the code before answering. Reply with what you
   found or changed:

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" reply   --file <artifact> --id c1 --author Claude --text "..."
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" resolve --file <artifact> --id c1 --author Claude --text "..."
   ```

   Resolve only when told to, or when the reply records a fix already made.
5. **Approve only for the reviewer, never for the author.** The approver is the reviewing seat, and
   `--ref` names the LAND message or comment id the approval rests on. The script refuses while a
   comment is open or when `--by` is the artifact's `author` (exit 1), and without `--by` or `--ref`
   (exit 2):

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" approve --file <artifact> --by <reviewer seat> --ref <LAND or comment id>
   ```

   An approved artifact with no open comment is the "phase done" signal other tools read.

## Adding a comment as a reviewer

```bash
node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" comment --file <artifact> \
  --author "<name>" --quote "<the line it is about>" --text "<the comment>"
```

## Rules

- Never resolve or approve on your own initiative; those are the reviewer's calls.
- Never edit the comment block with Write or Edit.

## Related Skills

- `/ork:create-plan` and `/ork:create-research`: write the artifacts whose comments this skill works through.
- `/ork:iterate-plan` and `/ork:iterate-research`: revise the body from comments, which this skill does not do.

