argdown Skill | Agent Skills

argdown

Argdown is a Markdown-flavored DSL for argument maps. Source is a .argdown text file; the argdown CLI parses it, reports syntax errors with location info, and exports to SVG/DOT/HTML/JSON.

When this skill fires

User asks to draft, edit, or lint a .argdown file
User wants to structure a debate / pro-con / objection tree / premise-conclusion argument and visualize it
User explicitly invokes $argdown or mentions "argument map", "argdown map", "claim/objection diagram"

Prerequisite

argdown CLI must be on PATH (/opt/homebrew/bin/argdown on this machine). Check with command -v argdown. If missing: npm install -g @argdown/cli. For SVG/PNG export, Graphviz is also needed: brew install graphviz.

Core workflow

Draft the .argdown file. Minimal skeleton:

===
title: <topic>
===

# <Section>

[Main claim]: One-sentence thesis.
  + <Supporting Arg>: Why the thesis holds.
  - <Counter Arg>: Why it might not.

<Supporting Arg>

(1) Premise.
(2) Premise.
-----
(3) [Main claim]

Lint — there is no separate lint subcommand. The default invocation parses and logs syntax errors with line/col:
```
argdown path/to/file.argdown
```
Or use scripts/lint.sh <file> (bundled): adds --throwExceptions so exit code is non-zero on parser errors — suitable for an iterate-until-clean loop.
Fix the reported errors. See "Gotchas" below for common ones.
Render once clean:
```
argdown map path/to/file.argdown ./svg -f svg
```
Or scripts/render.sh <file> [outdir] — wraps lint + map and prints the SVG path.
Iterate if the map looks wrong — adjust statements, relations, or --rankdir/label-mode flags.

Syntax cheat sheet

Full reference in references/syntax.md — load it when authoring a construct not covered here.

| Construct | Syntax | Notes | |---|---|---| | Statement (titled) | [Title]: text | Same title = same equivalence class | | Argument | <Title>: description | Angle brackets, not equivalence-class | | Premise-conclusion | (1) premise then ----- then (N) conclusion | Consecutive numbering, no blank lines inside | | Support | + <Arg> or + [Stmt] | Indented under parent | | Attack | - <Arg> | | | Contradiction | >< <Arg> | symmetric | | Undercut | _ <Arg> | targets an inference | | Direction | <- outgoing, +> incoming | reverse the arrow | | Reference | [Title] or <Title> alone | reuse without redefining | | Mention | @[Title] / @<Title> | inline reference inside prose | | Section | # Heading | groups in the map | | Frontmatter | === ... === block | YAML config; mode: strict toggles strict relations | | Inference detail | --\nModus Ponens\n{uses: [1,2]}\n-- | optional between premise list and conclusion | | Comment | // line, /* block */,  | |

What the linter catches vs tolerates

Argdown's parser is permissive — it recovers from many surface errors and renders something. lint.sh (via --throwExceptions) fails reliably only on a narrow set of hard parse errors. The rest must be caught by visually checking the rendered SVG.

Hard errors lint.sh will fail on:

Malformed PCS: missing ----- inference line, broken inference-detail block (-- / --), parser unable to reduce to a valid pcs rule.
Unclosed inline formatting that spans into the next block. Most common offender: an underscore in an identifier (redact_long.go, chat_session_id) opens an italic span, the parser keeps reading expecting a closing _, and chokes when it hits a blank line or unexpected token. Error message names statementContent > italic in the rule stack.

Silent / tolerated (renders despite looking broken):

Mismatched brackets like [Claim> — lexed as best-effort text.
Non-consecutive PCS numbering ((1), (3), (5)) — argdown re-numbers internally.
Pure gibberish lines — parsed as statements.
@[Title] mentions to titles that were never defined — warning at most.
Relation symbols at the wrong indent — silently re-interpreted as top-level.

Implication: after the lint passes, always render and skim the SVG before declaring the file correct.

Inline-formatting footguns

The body of a statement or argument description is parsed for markdown-style inline formatting before the rest of the rules apply. That means:

| Trigger | Effect | Mitigation | |---|---|---| | _word_ | italic span | Avoid bare underscores in identifiers — use - or wrap in backticks. | | *word* | italic span | Same as above for asterisks. | | **word** | bold span | Don't paste markdown bold into descriptions unless balanced. | | [Anything] mid-prose | parsed as a statement reference | Rephrase or use a different bracket style. | | <word> mid-prose | parsed as an argument reference | Same. |

When in doubt, write descriptions as plain prose and put code-like tokens in `backticks` — argdown treats them as inline code and leaves them alone.

Citing sources with YAML metadata

Any statement definition or reference can carry YAML metadata. Use this to attach a citation to a claim so the rendered map can hyperlink or label by source.

Recommended schema for a citation, fields in priority order:

| Field | Required when | Notes | |---|---|---| | source | always | DOI preferred — bare 10.xxxx/yyyy or https://doi.org/.... Fall back to a stable URL. | | author | recommended | Surname et al. is fine for multi-author. | | date | recommended | YYYY or YYYY-MM or YYYY-MM-DD. | | title | recommended | Short title is enough; full title in the YAML keeps the diagram label clean. |

Inline form — use when the metadata fits on one line:

[Climate trend]: Global mean surface temperature rose 1.2 °C since 1850. {source: 10.1126/science.abc1234, author: Smith et al., date: 2023, title: HadCRUT5 reanalysis}

Block form — opening { followed by a newline activates YAML block mode; the brackets are ignored and the body between them is parsed as YAML:

[Climate trend]: Global mean surface temperature rose 1.2 °C since 1850.
{
  source: 10.1126/science.abc1234
  author: Smith et al.
  date: 2023-04
  title: A reanalysis of HadCRUT5
}

For URL sources, quote the value so the colons don't confuse the YAML parser:

[IPCC AR6]: Anthropogenic warming is the dominant cause of observed warming since 1850.
{
  source: "https://www.ipcc.ch/report/ar6/wg1/"
  author: IPCC
  date: 2021
  title: AR6 Working Group I Summary
}

Same metadata schema works for <Argument> definitions — drop the YAML block right after the argument title or description.

Useful CLI flags

argdown -v <file> — verbose; shows the full AST.
argdown map -f svg <in> <outdir> — SVG via Graphviz.
argdown map -f dot <in> <outdir> — DOT only (no Graphviz needed).
argdown map --argument-labels title --statement-labels text — compact arg labels, full statement text.
argdown map --rankdir LR — left-to-right layout.
argdown html <in> <outdir> — standalone HTML with interactive map web-component.
argdown json <in> <outdir> — full parsed model as JSON for downstream tooling.
argdown --watch — re-run on file change.

Bundled scripts

scripts/lint.sh <file> — fail-fast lint (exit 1 on parser error). Use this in the iterate loop.
scripts/render.sh <file> [outdir] — lint then render to SVG; prints output path.

Both scripts assume argdown is on PATH.

Reference

references/syntax.md — full Argdown syntax reference from argdown.org. Load when authoring a construct not covered above.

Agent Skills: argdown

Install this agent skill to your local

Skill Files