trello-skill: Instructions file for Claude Code

AGENTS.md

Guidance for AI agents (and people) working in this repository.

What this is

The Trello skill pack for AI coding agents - a set of skills for working with Trello via the REST API. It follows the Agent Skills layout (skills/<name>/SKILL.md) and ships as a Claude Code plugin.

Layout

.claude-plugin/plugin.json          # plugin manifest (bundles all skills below)
skills/trello/                      # core board/list/card management + setup
skills/store-sort/                  # shopping list into store-aisle order (Tesco preset, as data)
skills/board-digest/                # board status snapshot
skills/due-radar/                   # due/overdue across boards
skills/life-manager/                # personal board setup, triage and coaching
install.sh / install-codex.sh       # local symlink installers (Claude / Codex)

Each skill is skills/<name>/SKILL.md plus optional scripts/ and references/.

Conventions

• Every script sources skills/trello/scripts/lib.sh, found relative to its own path, and makes no request of its own. lib.sh holds config loading, the ~/.trello migration, the one api() call, paging (api_get_all), local-time rendering (trello_jq_defs, local_now) and the shared helpers, so a fix to how a request is made lands once. Scripts in the other skills reach it as ../../trello/scripts/lib.sh and, when a partial install left trello out, stop with a message that names it.
• The trello core skill owns setup, lib.sh and the shared API scripts. Other skills (e.g. store-sort) call the core scripts by their ${CLAUDE_SKILL_DIR}/../trello/scripts/... path - ${CLAUDE_SKILL_DIR} is the calling skill's own directory, so ../trello is the sibling core skill (all skills sit side by side under the plugin / ~/.claude/skills/).
• That holds for the plugin and install.sh, not for a partial install: the skills CLI lets a user pick single skills. So the README install section and each of the four other SKILL.md files say trello must be installed beside them and give the npx skills add ... --skill trello --skill <name> command, and every script call in a SKILL.md code block starts at ${CLAUDE_SKILL_DIR}, never a bare script name. The suite checks both.
• SKILL.md references scripts via ${CLAUDE_SKILL_DIR} (the skill's own directory), which Claude Code substitutes for personal, project, and plugin installs alike. install.sh therefore symlinks the whole skill directory into ~/.claude/skills/ (no rewrite). install-codex.sh still rewrites the variable to the install path, since Codex does not substitute it.
• Shell scripts use set -e; errors go to stderr, structured output to stdout. api() in lib.sh retries an HTTP 429 three times (waiting 2, 4 and 8 seconds), then stops the script on any non-2xx answer with Trello's status and message, because Trello sends its errors as plain text, not JSON. So a verb handles success only, and prints "nothing found" only for a real empty result.
• A request for a long list - a board's cards, its actions, a card's comments, a list's cards - goes through api_get_all, never api_get. Trello answers at most 1000 results a request and says nothing when it stops; api_get_all pages with before until a page comes back short, and says "capped at N" on stderr if it has to stop first.
• Every time a script shows goes through local_time or local_date from trello_jq_defs, never .due[0:10]: Trello stores UTC, and its first ten characters are the UTC date, which is the wrong day near midnight for anyone not on UTC. The zone is named once per output, from local_now, because jq's %Z names it wrongly.
• Whether a list is a done list is is_done_list in trello_jq_defs, and nowhere else. A card in one with its due date not ticked is finished work: due-radar and board-digest name its list and never call it OVERDUE.
• Every change a SKILL.md asks for has a verb in a script. When a skill needs a new write - life-manager's board, list and label setup, or ticking a checklist item - add the verb to trello-boards.sh or trello-cards.sh and document it in trello/SKILL.md. A SKILL.md never has the agent build a request of its own, because that puts the key and token on the agent's command line.
• A script that writes many cards writes only the ones that must change, checks every write, and stops at the first one Trello refuses, naming the card and saying the rest was not done. life-board.sh sort --apply is the model: a sorted list gets no write, because every write moves a card's dateLastActivity and fills the board's activity.
• Any caller-supplied text sent to the API (card names, descriptions, comments) goes through curl --data-urlencode, never plain -d - -d sends the body raw, so an & silently truncates the value and a + arrives as a space.
• No secrets in the repo - credentials live under ~/.dbhq/trello/.
• trello-setup.sh stays interactive. The user types the key and token; with no terminal on stdin it changes nothing, prints the command for the user and exits 3. The token is read with read -rs, and config.json is written by jq from stdin, so a " or \ stays valid JSON and no credential is ever a process argument. The suite drives it through a real pseudo-terminal to prove all of this.
• Trigger phrases in a SKILL.md description name Trello, a board or the skill. An agent picks a skill by those phrases, so a bare "I'm stuck", "what's due" or "shopping list" takes requests that belong to a calendar, a decision skill or store-sort. Each skill does its own job once: trello has no sorting workflow and hands a shopping list to store-sort. The suite checks the phrases.
• House style: British English, plain hyphens.