Claude Code skill

qd guide teaches Claude the syntax. This skill teaches the judgment — the handful of rules that decide whether an agent working your boards is useful or destructive.

npm i -g @quietdesk/cli
qd login
qd skill install

That writes the skill to ~/.claude/skills/quietdesk/SKILL.md. Start a new Claude Code session to pick it up — skills load at session start.

Why a command instead of a file to copy

The skill ships inside the CLI package, so the guidance you install always matches the qd you are running. A skill describing tools your CLI doesn't have is worse than no skill at all.

What it teaches

Notes go in a comment, never the description. description_markdown is the brief — what the work is. A comment is what happened while doing it. Updating a description is a whole-field replace with no version guard on the MCP door, so an agent appending its progress there silently destroys the original spec. This has actually happened.

The pipeline has exactly one guard. Moves are unrestricted — any direction, stages may be skipped. The single enforced rule is that an agent identity cannot move a card to done; a human confirms. Older write-ups describe a legal-transition map and an operator ≠ approver rule. Both were retired on 2026-07-23, and the skill says so, so an agent doesn't invent workarounds for a constraint that no longer exists.

Filter server-side; never page-and-grep. qd cards list --board ENG --workflow-status ready narrows in the query. Piping an unfiltered list into jq answers from page one and looks identical when it's wrong.

Exit codes are the contract. 0 ok · 1 error · 2 auth · 3 not-found · 4 validation. Branch on them rather than matching on stderr text.

A missing MCP tool is almost never a missing feature. MCP tools bind at session start, so a tool absent from a running session usually means a stale binding, not a server without it. Two separate sessions have burned real effort here — one guessed 14 tool names, another designed a nine-call workaround around a tool that was live the whole time. The skill's instruction is to stop and report rather than route around it.

It also covers the identifier rules (every card command takes GEN-1, not just a uuid), which creates are safe to retry, and the known gaps worth not hunting for — member_id ≠ user_id, no bulk operations, and todos_create not attaching to a card.

The other subcommands

Command	What it does
qd skill install	Write the skill into ~/.claude/skills/quietdesk/
qd skill install --force	Replace a copy you have edited locally
qd skill print	Print the markdown to stdout
qd skill path	Show where an install would write, without writing

An install that finds an unchanged copy already in place reports already up to date and exits 0, so re-running it after a CLI upgrade is safe. If it finds a copy you have edited, it refuses and exits 2 rather than overwriting your version — pass --force when you do want the packaged one back.

CLAUDE_CONFIG_DIR overrides the destination if your Claude Code config lives somewhere other than ~/.claude.

Rolling it out to a team

Point people at three lines — install, log in, install the skill. Everyone lands on the same conventions without a document to circulate, and the skill updates with the CLI rather than drifting from it.

For MCP clients rather than a terminal, see the MCP server page; the same rules apply, because both doors run the same service.