| name | swamp-report |
| description | Run, configure, and view reports for swamp models and workflows. Use when running reports via CLI, configuring report selection in definition YAML, viewing report output, or filtering reports by label. Do NOT use for creating report extensions (that is swamp-extension) or debugging report failures (that is swamp-troubleshooting). Triggers on "run report", "swamp report", "model report", "report output", "report label", "skip report", "report results", "cost report", "audit report", "workflow report", "report get", "report filtering".
|
Swamp Report Skill
Create and run reports that analyze model and workflow executions. Reports
produce markdown (human-readable) and JSON (machine-readable) output. All
commands support --json for machine-readable output.
When to Create a Report
Create a report extension when you need a repeatable pipeline to transform,
aggregate, or analyze model output. If the analysis will be run more than once
or should be stored alongside model data, a report is the right choice.
Verify CLI syntax: If unsure about exact flags or subcommands, run
swamp report --help or swamp model method run --help for the complete,
up-to-date CLI schema.
Quick Reference
| Task | Command |
|---|
| Get a stored report | swamp report get <report-name> --model <model> |
| Get report as markdown | swamp report get <report-name> --model <model> --markdown |
| Get report as JSON | swamp report get <report-name> --model <model> --json |
| Cap total output width | swamp report get <report-name> --model <model> --max-width 120 |
| Cap column width | swamp report get <report-name> --max-col-width 60 |
| Run method with reports | swamp model method run <model> <method> |
| Skip all reports | swamp model method run <model> <method> --skip-reports |
| Skip report by name | swamp model method run <model> <method> --skip-report <n> |
| Skip report by label | swamp model method run <model> <method> --skip-report-label <l> |
| Run only named report | swamp model method run <model> <method> --report <n> |
| Run only labeled reports | swamp model method run <model> <method> --report-label <l> |
| Workflow with reports | swamp workflow run <workflow> |
| Workflow skip reports | swamp workflow run <workflow> --skip-reports |
End-to-End Workflow
- Create the report file in
extensions/reports/ — export a report
object with name, description, scope, optional labels, and execute.
- Register in manifest — add the filename to the
reports: list in
manifest.yaml. Verify with swamp model get <model> --json to confirm the
report appears in the resolved report set.
- Configure in definition YAML — add the report name to
reports.require:
in the model or workflow definition if it should run beyond the model-type
defaults. Use reports.skip: to exclude reports you don't need.
- Run and verify — execute a model method, then use
swamp report get <report-name> --model <model> to confirm the report
produces valid markdown and JSON output without errors.
- Check stored output — run
swamp data query 'tags.type == "report"' to
verify the report artifact was persisted correctly.
Creating Report Extensions
To create a new report extension, use the swamp-extension skill. It covers the
TypeScript authoring workflow, export contract, scopes, reading execution data,
and testing.
Three-Level Report Control Model
Reports are controlled at three levels, from most general to most specific:
1. Model Type Defaults (TypeScript ModelDefinition)
The reports field on model definitions lists standalone report names that are
defaults for any model of this type:
export const model = {
type: "@myorg/ec2",
version: "2026.03.01.1",
reports: ["@myorg/cost-report", "@myorg/drift-report"],
};
2. Definition YAML Overrides (reportSelection)
The reports: field in definition YAML provides per-definition overrides.
require adds reports beyond model-type defaults. skip removes reports from
the defaults.
id: 550e8400-e29b-41d4-a716-446655440000
name: my-vpc
version: 1
tags: {}
reports:
require:
- "@myorg/compliance-report"
- name: security-audit
methods: ["create", "delete"]
skip:
- "@myorg/drift-report"
globalArguments:
cidrBlock: "10.0.0.0/16"
methods:
create:
arguments: {}
3. Workflow YAML Overrides
The reports: field in workflow YAML controls workflow-scope reports and can
also override model-level reports for the workflow run.
name: deploy
reports:
require:
- "@myorg/workflow-summary"
skip:
- "@myorg/cost-report"
Filtering Semantics and Precedence
The candidate set is built from model-type defaults plus require, minus
skip, with CLI flags applied last. skip always wins over require, and
require makes a report immune to CLI skip flags. See
references/filtering.md for the full set composition
and precedence rules.
Publishing Reports
Reports can be published as part of extensions via the manifest reports:
field:
manifestVersion: 1
name: "@myorg/reports"
version: "2026.03.01.1"
description: "Cost and compliance reports"
reports:
- cost_report.ts
- compliance_report.ts
For the full publishing workflow, use the swamp-extension-publish skill. It
provides a state-machine checklist that enforces all prerequisites before
allowing a push.
CLI Flags
model method run / workflow run
| Flag | Description |
|---|
--skip-reports | Skip all reports (except definition-required) |
--skip-report <name> | Skip a specific report by name (repeatable) |
--skip-report-label <label> | Skip reports with this label (repeatable) |
--report <name> | Only run this report (repeatable, inclusion) |
--report-label <label> | Only run reports with this label (repeatable) |
report search
Browse stored report results across all models and workflows. Pass an optional
[query] argument for a case-insensitive substring match; the flags below are
exact matches.
| Flag | Description |
|---|
[query] | Substring match on report name, data name, or variant |
--model <name> | Filter to a specific model |
--workflow <name> | Filter to a specific workflow |
--scope <scope> | Filter by report scope (method, model, workflow) |
--type <name> | Filter by exact report type name (e.g. @myorg/cost) |
--label <label> | Filter by report label (repeatable) |
report get
| Flag | Description |
|---|
--model <name> | Scope to a specific model |
--workflow <name> | Scope to a specific workflow |
--version <version> | Get specific version (default: latest) |
--variant <variant> | Select a specific forEach variant |
--markdown | Output as plain markdown instead of terminal-formatted |
--max-width <width> | Cap total output width in columns |
--max-col-width <width> | Cap individual table column width in characters |
Report Data Storage
Report results are automatically persisted as data artifacts:
- Markdown: data name
report-{reportName}, content type text/markdown
- JSON: data name
report-{reportName}-json, content type
application/json
- Lifetime: 30 days, garbage collection keeps 5 versions
- Tags:
type=report, reportName={name}, reportScope={scope}
Access stored reports via data query (see swamp-data skill):
swamp data query 'tags.type == "report"'
swamp data get my-model report-cost-estimate --json
Output
Three output modes: log (default, terminal-formatted), markdown
(--markdown, raw pipe-tables for pasting), JSON (--json, structured
detail for agents).
Width controls (log and markdown modes): --max-width N caps total output
width. --max-col-width N truncates individual table columns with …. Both
combine. Env vars: SWAMP_REPORT_MAX_WIDTH, SWAMP_REPORT_MAX_COL_WIDTH.
When to Use Other Skills
| Need | Use Skill |
|---|
| Work with models | swamp-model |
| Create/run workflows | swamp-workflow |
| Create report extensions | swamp-extension |
| Create custom model types | swamp-extension |
| Manage model data | swamp-data |
| Repository structure | swamp-repo |
| Understand swamp internals | swamp-troubleshooting |
References
