tzst

Overview of tzst skill

What the tzst skill helps you do

The tzst skill is a practical guide for using the tzst command-line tool to create, inspect, test, and extract .tzst and .tar.zst archives. It is most useful when you already know the file paths you want to work with and need the right command, flags, and safety choices faster than a generic prompt would provide.

Who should use tzst

This tzst skill fits developers, ops users, and automation builders who need reliable archive workflows for local files, scripts, CI jobs, or one-off support tasks. It is especially relevant if you want machine-readable output, controlled extraction behavior, or a no-surprises install path.

Real job-to-be-done

Most users are not looking for a repo tour. They want to answer questions like: How do I install tzst? Which command creates vs extracts? How do I avoid overwriting files? How do I filter what gets extracted? How do I use tzst for File Automation with JSON-friendly output and predictable flags?

Key differentiators

Compared with an ordinary prompt, tzst is narrower and therefore more actionable. It focuses on the CLI, not a Python API; it surfaces safe defaults; and it points users toward concrete command patterns such as a for create, x for structured extract, e for flat extract, l for listing, and t for archive testing.

What matters before you install

The biggest adoption blockers are usually simple: whether tzst is already available on your system, whether you want a Python-based install or a standalone binary, and whether your task is truly about tzst rather than generic tar or zip. If your need is CLI archive handling, this skill is a strong fit. If you need from tzst import ..., it is not the right primary guide.

How to Use tzst skill

Start with install and preflight

Before asking the model to do anything substantial, verify that tzst exists in your environment:

tzst --version
tzst --help

If it is missing, the repository guidance points to these install paths:

uv tool install tzst
pip install tzst

If you do not want a Python install, use the standalone release binaries from https://github.com/xixu-me/tzst/releases/latest.

Know when to invoke tzst skill

Use tzst usage guidance when the request involves any of the following:

• creating a .tzst archive
• extracting .tzst or .tar.zst
• flattening extracted contents
• listing archive entries
• testing archive integrity
• choosing compression levels
• using streaming mode
• filtering extracted paths
• selecting conflict behavior
• producing output suitable for scripts

Do not lead with this skill for unrelated archive formats or Python library questions.

The core command map

The quickest way to use tzst well is to map your goal to the right subcommand:

• tzst a archive.tzst files... for create
• tzst x archive.tzst for extract while preserving paths
• tzst e archive.tzst for flat extraction
• tzst l archive.tzst for list
• tzst t archive.tzst for test

This matters because many bad outcomes come from choosing e when you actually wanted x, or extracting without thinking about conflicts and output location.

Prefer structured extraction over flat extraction

In normal workflows, tzst x is the safer default because it preserves directory structure. Use tzst e only when flattening is explicitly desired. That distinction is important for tzst for File Automation, where flattening can create naming collisions or make downstream file matching harder.

Inputs the skill needs from you

To produce a high-quality command, the skill needs concrete operating details:

• archive path or desired output archive name
• source files or directories
• destination directory for extraction
• whether flattening is wanted
• whether overwriting is allowed
• any path filters
• whether output should be script-friendly
• whether you prefer Python install or standalone binary

If you omit these, the model can still suggest syntax, but it cannot give a low-risk command.

Turn a rough goal into a strong tzst prompt

Weak prompt:

Help me use tzst.

Stronger prompt:

I need a tzst command to extract archive.tzst into ./out, preserve paths, avoid overwriting existing files, and only extract files under docs/. Assume tzst is already installed.

Why this is better: it gives the skill the archive, destination, extraction mode, conflict expectation, and filter scope in one pass.

Prompt pattern for archive creation

Use a prompt like this when creating archives:

Give me a tzst create command for backup.tzst from ./src and ./docs, use a higher compression level, and explain any safety or performance tradeoffs.

This lets the skill choose tzst a, surface -l or --level, and note where defaults are usually sufficient versus when extra compression may cost time.

Prompt pattern for scripting and automation

For tzst usage inside shell scripts or CI, ask for commands with machine-readable expectations:

I need tzst for File Automation in a CI job. Show commands to test an archive, list contents, and return output that is easy to parse in a script.

This steers the skill toward JSON-oriented or script-safe output paths where supported, and toward stable command sequences instead of interactive advice.

Suggested workflow for real tasks

A reliable workflow is:

1. confirm install with tzst --version
2. test availability with tzst --help
3. choose the subcommand from your real goal
4. specify destination, filters, and conflict policy
5. test or list before destructive extraction when risk is high
6. run the final command
7. only then script it into automation

This sequence reduces avoidable extraction mistakes and makes troubleshooting easier.

Repository files worth reading first

If you want to validate the skill before adopting it, start here:

• skills/tzst/SKILL.md
• skills/tzst/references/cli-reference.md

SKILL.md tells you when the skill should trigger. references/cli-reference.md is the fastest file for install commands, command mapping, and flag selection.

Practical flag choices that change outcomes

A few options materially affect results:

• -l or --level changes compression level on creation
• -o controls extraction destination
• --streaming matters for large or pipeline-oriented workflows
• --filter limits what gets extracted
• --conflict-resolution helps avoid accidental overwrites
• --no-atomic changes write behavior during creation

These are not cosmetic flags. They define safety, performance, and script behavior.

Common misfires during tzst install and usage

The main mistakes are predictable:

• trying to use the skill for Python imports instead of CLI tasks
• skipping preflight and discovering tzst is not installed only after building a workflow
• using flat extraction when path-preserving extraction was intended
• not specifying conflict handling in directories with existing files
• asking for “a command” without naming paths, filters, or outputs

tzst skill FAQ

Is tzst skill good for beginners

Yes, if your task is concrete. The tzst guide is easier for beginners when they already know the archive they have and the result they want. It is less helpful for vague “teach me archives” requests.

What is the difference between tzst and a generic AI prompt

A generic prompt may give plausible archive advice that is not aligned to tzst subcommands or flags. The tzst skill narrows the model to the real CLI workflow, install choices, and command vocabulary that users actually need to execute.

When should I not use tzst

Do not use tzst as the main guide for:

• generic zip or tar questions with no tzst involvement
• Python API usage such as from tzst import ...
• archive tasks where another installed tool is the true requirement

The skill is deliberately CLI-specific.

Is tzst suitable for automation

Yes. This is one of the stronger reasons to use it. The skill explicitly covers list, test, filtering, conflict control, and machine-readable output considerations that matter in shell scripts and CI.

What is the best tzst install path

For many users, uv tool install tzst is the cleanest install. pip install tzst works if Python package installs already fit your environment. If you want minimal dependency overhead, the standalone binary release is the better path.

Do I need to read the whole repository first

No. For an install decision, you usually only need SKILL.md and references/cli-reference.md. That is enough to judge fit, command coverage, and whether the skill will reduce guesswork for your use case.

How to Improve tzst skill

Give tzst complete task context

The fastest way to improve tzst results is to provide operational specifics up front. Include the archive name, source paths, target directory, overwrite policy, flattening preference, and whether the command must be safe for scripting. Better inputs produce commands you can actually run.

State your risk tolerance explicitly

If the task touches important files, tell the skill whether it should optimize for safety over brevity. That pushes it toward listing, testing, path-preserving extraction, and explicit conflict settings rather than minimal commands.

Ask for command plus rationale

A good prompt format is:

Give me the exact tzst command, explain each important flag briefly, and mention any safer alternative if the destination already contains files.

This improves trust and helps you catch wrong assumptions before execution.

Request iteration after the first command

The best tzst guide usage is iterative. After the first output, refine it with environment details:

Now adapt that command for a standalone binary install and a CI environment where the output must be easy to parse.

This is more effective than restarting from scratch.

Use file samples and path examples

If filtering or flattening matters, include representative paths. Example:

Archive contains docs/api/index.md, docs/user/intro.md, and src/main.py. I only want docs/ extracted into ./site-content.

That level of detail helps the skill choose the right extraction mode and filter behavior.

Catch common failure modes early

Ask the skill to check for these before finalizing a command:

• missing tzst installation
• wrong subcommand for the job
• accidental path flattening
• archive overwrite or extraction conflicts
• unsupported assumptions about output format

This is where tzst skill adds real value over an ordinary one-line CLI answer.

Improve tzst for File Automation with stable workflows

When using tzst for File Automation, ask for a sequence rather than a single command: preflight, list or test, execute, and verify. Stable automation usually comes from predictable steps, not from the shortest possible syntax.

Validate against the reference file

If a command feels uncertain, compare it with references/cli-reference.md. That file is the fastest cross-check for subcommands, install choices, and the flags most likely to affect correctness.

Suggest improvements back to the skill

If you find repeated ambiguity, improve the skill by adding more decision-oriented examples around:

• x vs e
• safe conflict-resolution defaults
• filtering examples with realistic paths
• automation-oriented output patterns
• install choice guidance for Python vs standalone binary

Those additions would make the tzst skill even more useful at decision time, not just execution time.