Agent Skill

name: agent-first-data description: Apply Agent-First Data naming and output conventions when writing structured data, configs, logs, transport payloads, or CLI output in any language. disable-model-invocation: true allowed-tools: Bash, Read, Edit, Write, Glob, Grep

This skill content is tool-agnostic. It can be used by any AI coding agent workflow. The frontmatter keys at the top are metadata for skill runners and do not change the AFDATA conventions.

Three parts:

1. Naming — encode units and semantics in field names so agents parse structured data without external schemas
2. Output — suffix-driven formatting with key stripping, value formatting, and automatic secret redaction
3. Protocol — optional JSONL protocol with code (required) and trace (recommended)

Part 1: Naming Convention

The field name is the schema. Always encode units and semantics in the field name.

Duration

Timestamps

Size

_size parsing rules (binary): B=1, K=1024, M=1024², G=1024³, T=1024⁴. Case-insensitive.

parse_size("10M") → 10485760. Returns null for invalid or negative input.

Percentage

Currency

Bitcoin:

Fiat — _{iso4217}_cents for currencies with 1/100 subdivision, _{iso4217} for currencies without:

Sensitive

All CLI output formats (JSON, YAML, Plain) automatically redact _secret fields. Matching recognizes _secret and _SECRET only — no mixed case.

Environment variables

Same suffixes, UPPER_SNAKE_CASE:

DATABASE_URL_SECRET=postgres://user:pass@host/db
CACHE_TTL_S=3600
TOKEN_VALIDITY_HOURS=24

No suffix needed

Fields whose meaning is obvious: callback_url, redb_path, proof_count, search_enabled, method, domain, model.

Database columns

Use suffixes on generic types (INTEGER, BIGINT, TEXT). Native types that carry semantics (TIMESTAMPTZ, INTERVAL) don’t need suffixes.

ORM struct fields preserve the suffix: duration_ms: i64, not duration: i64.

Common mistakes

Part 2: Output Processing

Three output formats. YAML and Plain apply key stripping + value formatting.

Formats

• JSON — single-line, original keys, raw values, no sorting (machine-readable), secrets redacted
• YAML — multi-line, keys stripped, values formatted, secrets redacted
• Plain — single-line logfmt, keys stripped, values formatted, secrets redacted

Key stripping (YAML and Plain)

Remove recognized suffix from key. Longest match first, exact lowercase or uppercase only:

1. _epoch_ms, _epoch_s, _epoch_ns
2. _usd_cents, _eur_cents, _{code}_cents
3. _rfc3339, _minutes, _hours, _days
4. _msats, _sats, _bytes, _percent, _secret
5. _btc, _jpy, _ns, _us, _ms, _s

_size is NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting).

Value formatting (YAML and Plain)

• _ms < 1000 → {n}ms; ≥ 1000 → seconds (1280 → 1.28s, 5000 → 5.0s)
• _s, _ns, _us → append unit (3600s, 450000ns, 830μs)
• _minutes, _hours, _days → append unit (30 minutes)
• _epoch_ms/_epoch_s/_epoch_ns → RFC 3339 (negative = pre-1970)
• _rfc3339 → pass through
• _bytes → human-readable (456789 → 446.1KB, -5242880 → -5.0MB)
• _size → pass through
• _percent → append %
• _msats → {n}msats, _sats → {n}sats, _btc → {n} BTC
• _usd_cents → $X.XX, _eur_cents → €X.XX, _jpy → ¥X,XXX, _{code}_cents → X.XX CODE
• _secret → ***

Type constraints: _bytes/_epoch_* require integer. _usd_cents/_eur_cents/_jpy/_{code}_cents require non-negative integer. Duration/Bitcoin/_percent accept any number. Wrong type → raw value + original key.

Plain logfmt details

• Nested keys use dot notation: trace.duration=1.28s
• Values with spaces are quoted: message="uploading chunks"
• Arrays comma-joined: fields=email,age
• Null → empty value: RUST_LOG=
• Sort by full dot path (JCS / UTF-16 code unit order)

Key ordering

YAML and Plain sort keys (after stripping) by UTF-16 code unit order (JCS, RFC 8785). For ASCII keys this equals byte-order sorting.

Part 3: Protocol Template (Optional)

Every output line carries a code field:

Channel policy:

• stdout is the only protocol/log stream for machine-readable events
• runtime protocol events MUST NOT be emitted on stderr
• stderr is reserved for unrecoverable pre-protocol startup failures only

Recommended enforcement:

• Rust: enable clippy print_stderr = "deny" and disallow std::eprintln / std::io::stderr
• Go/Python/TypeScript: add source-policy tests that fail if runtime sources reference stderr APIs

Templates

{"code": "log", "event": "startup", "version": "0.1.0", "argv": ["tool", "--log", "startup"], "config": {...}, "args": {...}, "env": {...}}
{"code": "ok", "result": {...}, "trace": {"duration_ms": 12, "source": "redb"}}
{"code": "error", "error": "message", "trace": {"duration_ms": 3}}
{"code": "not_found", "resource": "user", "id": 123, "trace": {"duration_ms": 8}}

Always include trace for execution context: duration, token counts, cost, data source. Startup payload fields are tool-defined; config is recommended, while version/argv/args/env are optional.

Same structure, any transport

All use code / result / error / trace. Do not split protocol events across stdout and stderr.

Using the Library

15 public APIs and 2 types (same across all languages):

Rust

use agent_first_data::{build_json_ok, build_json_error, build_json, output_json, output_yaml, output_plain, internal_redact_secrets, parse_size};
use agent_first_data::{OutputFormat, cli_parse_output, cli_parse_log_filters, cli_output, build_cli_error};

Python

from agent_first_data import build_json_ok, build_json_error, build_json, output_json, output_yaml, output_plain, internal_redact_secrets, parse_size
from agent_first_data import OutputFormat, cli_parse_output, cli_parse_log_filters, cli_output, build_cli_error

TypeScript

import { buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "agent-first-data";
import { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError } from "agent-first-data";

Go

import afdata "github.com/agentfirstkit/agent-first-data/go"

afdata.OutputPlain(value)
afdata.ParseSize("10M")
afdata.CliParseOutput("json")
afdata.BuildCliError("--output: invalid value 'xml'")

CLI Helpers Pattern

When building a CLI tool on AFDATA, always use the CLI helpers to parse --output and --log flags. This ensures consistent behavior and error format across all tools:

--output json|yaml|plain    → cli_parse_output
--log startup,request,...   → cli_parse_log_filters (trim, lowercase, dedup, remove empty)
parse errors                → build_cli_error + output_json + exit 2

Key rule: use try_parse() / try_parse_from() (not parse()) in Rust/clap so that parse errors go to stdout as JSONL, not stderr as plain text.

AFDATA Logging

Structured logging that outputs via the library’s own output_json/output_plain/output_yaml. Each language integrates with its native logging ecosystem. All three formats apply the same suffix processing, key stripping, and secret redaction as the core output API.

Init (pick one format per process)

Rust requires cargo add agent-first-data --features tracing.

Spans (add fields to all log events in scope)

// Rust — tracing spans
let span = info_span!("request", request_id = %uuid);
let _guard = span.enter();

// Go — context-based
ctx := afdata.WithSpan(ctx, map[string]any{"request_id": uuid})
logger := afdata.LoggerFromContext(ctx)

# Python — contextvars
with span(request_id=uuid):
    logger.info("Processing")

// TypeScript — AsyncLocalStorage
await span({ request_id: uuid }, async () => {
  log.info("Processing");
});

Output fields

Every log line contains: timestamp_epoch_ms, message, code (defaults to log level, overridable), plus span fields and event fields.

CLI Flags

CLI tools that use AFDATA should support output and logging flags:

--output json|yaml|plain    # default is tool-defined (interactive → yaml, scripting/logging → json)
--log startup,request,progress,retry,redirect
--verbose                   # shorthand for all log categories

• Protocol output (build_json_* + output_*) follows --output
• Log format follows --output or a separate --log-format flag if independent control is needed
• --help SHOULD expand all subcommands and flags in one output. myapp sub --help scopes to that subtree. --help-markdown outputs Markdown for doc generation. Rust: use cli_render_help() and cli_render_help_markdown() from the cli-help / cli-help-markdown features.

Review Checklist

When reviewing code that produces structured output:

1. Every numeric field with a unit has the correct suffix (_ms, _bytes, _sats, _percent, etc.)
2. Timestamps use _epoch_ms / _epoch_s / _rfc3339 — never bare timestamp: 1707868800
3. Sensitive values end in _secret and are redacted in all output paths
4. Transport payloads / CLI output use code / result / error / trace structure
5. Config files use the same suffixes as output
6. No unit-less ambiguous fields (timeout: 30 — 30 what?)
7. Config size values use _size suffix (buffer_size: "10M", not buffer: "10M")
8. Environment variables follow UPPER_SNAKE_CASE with the same suffixes
9. Logging uses AFDATA init functions (init_json/init_plain/init_yaml) — not raw println!/fmt.Println/console.log for structured output
10. Database columns use AFDATA suffixes on generic types (duration_ms INTEGER, not duration INTEGER); native types like TIMESTAMPTZ don’t need suffixes
11. CLI flag parsing uses cli_parse_output/cli_parse_log_filters/build_cli_error — not custom reimplementations; uses try_parse() not parse() in Rust so clap errors go to stdout as JSONL