Claude Code · Codex CLI · Skill
A single drop-in skill that turns an agent into a competent Fizzy operator — onboarding, daily card and comment CRUD, and an end-to-end Jira-to-Fizzy migrator, with every rendering quirk and silent pagination trap documented in line.
$ git clone https://github.com/cskwork/fizzy-skill.git \
~/.claude/skills/fizzy
# Codex users: same SKILL.md, different home
$ git clone https://github.com/cskwork/fizzy-skill.git \
~/.codex/skills/fizzyFizzy is good software with a few rough edges. Each of these has cost real time to discover; the skill encodes the workaround so an agent never relearns them.
Bodies are stored as HTML and auto-converted to a plain-text-with-bullets format.
**bold** shows up as literal asterisks. The server accepts HTML but
silently strips <h1>…<h6>,
<strong>, <hr>, <a href>,
<img>, <pre>, and <table>.
The skill ships an ADF-to-HTML converter that compensates for every stripped tag.
--json is a global flag
Place it before the subcommand or it is silently ignored.
fizzy-cli --json comment list 36 works;
fizzy-cli comment list 36 --json does not, and there is no warning.
comment list paginates silently
Page one returns roughly three items, with no has_more hint.
Any script that "wipe comments by user X" without looping leaves orphans behind.
The skill loops until the filtered list is empty.
Right after auth login, board list errors cryptically until
you run fizzy-cli account set <SLUG>, even if the account is the only one.
auth login --email --code re-issues a code on every call, invalidating the
one the user already pasted from the inbox. The skill includes a curl two-step that keeps
the pending token in shell scope and verifies cleanly.
Install via Homebrew or build from source (with the go install footgun called out).
Point at the host, authenticate via PAT or magic-link curl two-step, set the default account,
verify with a throwaway card.
Board / card / comment CRUD with the markdown gotchas baked in.
User-only comment filtering, pagination-safe wipe, retry on context deadline exceeded.
One command pulls a Jira issue (description, attachments, comments) and produces a parent card plus optional numbered sub-cards. ADF is converted to Fizzy-optimal hybrid HTML so headings, lists, and tables survive.
One git clone into your CLI’s skill directory. No build step.
git clone https://github.com/cskwork/fizzy-skill.git \
~/.claude/skills/fizzyThe skill loads automatically the next time Claude Code reads your skills directory.
git clone https://github.com/cskwork/fizzy-skill.git \
~/.codex/skills/fizzyCodex reads the same SKILL.md front-matter format. One clone serves either CLI.
fizzy-cli on PATH — install with brew install tobiasbischoff/tap/fizzy-cli, or clone and go build. (go install does not work; the module declares the short form module fizzy-cli.)acli authenticated to your Atlassian site, plus a Personal Access Token in ~/.config/fizzy/.env (chmod 600) — acli’s OAuth scope cannot fetch attachment content.export FIZZY_HOST="https://fizzy.example.com"
export FIZZY_TOKEN="..." # PAT from Fizzy account settings
fizzy-cli config set --base-url "$FIZZY_HOST"
fizzy-cli auth login --token "$FIZZY_TOKEN"
fizzy-cli account set <SLUG> # required even with one account
fizzy-cli board listfizzy-cli card create --board-id <ID> \
--title "fizzy setup test" --description "ok" --status published
fizzy-cli --json comment list <N> \
| jq -r '.[] | select(.creator.name != null) | .id'python3 scripts/jira_to_fizzy.py \
--from-json /tmp/PROJ-123.json \
--board <fizzy-board-id> \
--site your-site.atlassian.net \
--split-numbered
Cached JSON is produced by the Atlassian MCP getJiraIssue tool.
Pass --wipe-user-comments <username> on --card <N>
to clean a previous run before re-importing.
The single most useful table in this repo. Send HTML; assume nothing about the result.
| Tag | Result in the UI |
|---|---|
<p>...</p> | Paragraph with blank-line separation |
<ul><li>X</li></ul> | • X with auto bullet |
<ol><li>X</li></ol> | 1. X with auto numbering |
nested <ul> in <li> | Two-space indented bullet |
<blockquote>X</blockquote> | Wrapped in curly quotes |
<br> | Line break inside a paragraph |
| Tag | Fizzy behavior | Workaround |
|---|---|---|
<h1>…<h6> | Shown as plain text, no marker | Wrap in <p>[Section]</p> or use a box-drawing rule |
<strong> / <em> | Markers stripped | Use bracket labels or <p> structure to carry weight |
<hr> | Disappears | Emit <p>━━━━━━━━━━━━</p> |
<a href="X">label</a> | Text only, URL gone | Print the URL inline: <p>label: X</p> |
<img> | Disappears | Use the card’s main-image slot (card update --image PATH) |
<pre> / <code> | Markers stripped, contents flattened | Wrap in box-drawing characters; render line breaks as <br> |
<table> | All cells concatenated, no structure | Render rows as <p>| a | b |</p> with <br> between rows |
scripts/adf_to_fizzy.py automates every cell above when migrating from Atlassian Document Format.
MIT-licensed, single-skill, no build step.