tzst— agent skill

Use this skill for the tzst command-line interface. Default to execution when the user clearly wants a real archive action and the required paths or archive names are already known.

This skill is CLI-only. If the user is asking about Python code such as from tzst import ..., treat that as a general Python library or API documentation task instead of using this skill as the main guide.

When to Use

Use this skill when the user:

• mentions .tzst or .tar.zst archives
• wants to create, extract, flatten, list, or test a tzst archive
• needs help installing tzst or choosing CLI flags
• wants machine-readable tzst output for scripting or automation
• needs safe conflict handling or extraction filter guidance

Do not use this skill for generic tar, zip, or Python API questions unless tzst is actually part of the request.

Preflight

1. Check whether tzst is available with tzst --version or tzst --help.
2. If it is missing, prefer one of these installation paths:

• uv tool install tzst
• pip install tzst
• a standalone release binary from <https://github.com/xixu-me/tzst/releases/latest> when the user does not want a Python installation

1. Re-run tzst --version or tzst --help before doing real work.

Workflow

1. Decide whether the request is execution or guidance.

Requests like "archive these files", "extract this backup", "list what is inside", "test this archive", or "install tzst" are execution intent.

1. Choose the command that matches the request:

• a, add, create for archive creation
• x, extract for normal extraction with directory structure preserved
• e, extract-flat only when the user explicitly wants flattened output
• l, list for archive inspection
• t, test for integrity checks

1. If the user wants to extract only a few members and the member names are uncertain, list first.
2. Load references/cli-reference.md when you need the command matrix, exact flag names, or copy-paste examples.

Safe Defaults

• Prefer x over e unless flattening is explicitly requested.
• Keep --filter data as the default extraction mode.
• Use --filter tar only when the user needs standard tar-style compatibility.
• Use --filter fully_trusted only when the user explicitly says the archive source is completely trusted.
• Keep atomic archive creation enabled. Only reach for --no-atomic when the user explicitly wants it.
• Prefer --streaming for large archives or memory-constrained environments.
• For automation or pipelines, prefer tzst --json --no-banner ....
• For automated extraction, require an explicit non-interactive --conflict-resolution choice such as replace_all, skip_all, or auto_rename_all.
• Do not combine --json with interactive conflict prompting.

Scripting Notes

• Put global flags before the subcommand in examples, such as tzst --json --no-banner l archive.tzst.
• Use exit codes in scripts: 0 for success, 1 for operation errors, 2 for argument parsing errors, and 130 for interruption.
• When archive naming matters, tell the user that tzst may normalize a creation target to .tzst or .tar.zst.

Common Mistakes

• Using e when the user expected the original directory structure to be preserved
• Recommending fully_trusted for archives from an unknown or untrusted source
• Forgetting an explicit conflict strategy for non-interactive extraction
• Treating a Python API question as a CLI question
• Guessing flags from tar habits instead of checking the bundled reference or the installed CLI help