Metadata-Version: 2.5
Name: tracemantle
Version: 1.7.0
Summary: Cross-agent skill quality gate for SKILL.md files conforming to the agentskills.io specification
Project-URL: Repository, https://github.com/moonrunnerkc/tracemantle
Project-URL: Issues, https://github.com/moonrunnerkc/tracemantle/issues
Author: moonrunnerkc, Aftermath Technologies Ltd
License: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.5; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: tomli>=2.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: tiktoken
Requires-Dist: tiktoken>=0.7; extra == 'tiktoken'
Description-Content-Type: text/markdown

# TraceMantle

TraceMantle checks `SKILL.md` files for developers who write or maintain agent skills, finding invalid frontmatter, missing files, and portability problems before commit or CI. Optional evidence tracking helps you check whether earlier results still apply after a skill or its helpers change.

## Quick start

Requires Python 3.10 or later. Create an isolated environment and install the published release:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install tracemantle==1.7.0
tracemantle hello/SKILL.md
```

Use the path to your own skill in the last command. On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1`. Need a first file? Copy the small [getting-started example](docs/getting-started.md#validate-your-first-skill).

Basic validation runs locally with no account, evaluator, signing key, or evidence policy. The default token estimate is offline.

## Read the result

The getting-started example produces:

```text
✔ PASS  hello/SKILL.md
            · info              description.quality-score  Description quality score: 95/100.

Checked 1 file: 1 passed, 0 failed
```

This file has no validation errors. The score is heuristic advice. For failures, fix the reported rule at the named file and line, then rerun. Passing file validation does not prove that a skill behaves correctly in a live agent.

Scan a directory with `tracemantle skills/`. Errors return a nonzero exit code; add `--strict` to fail on warnings too. Use `--format json` for structured results or `--help` for options.

## Optional evidence checks

Use evidence checks when a release needs approved results or you need to detect helper changes that invalidate earlier results. The [evidence workflow](docs/evidence-workflow.md) distinguishes manual approval from protected automation and neutral JSON imports.

## Task guides

- [Getting started](docs/getting-started.md): create and validate a skill.
- [CI setup](docs/ci.md): validate skills on pull requests.
- [Evidence workflow](docs/evidence-workflow.md): import results and approve their use.
- [CLI reference](docs/generated-reference.md): commands and configuration.
- [Troubleshooting](docs/getting-started.md#troubleshooting): understand diagnostics and exit codes.

[Contribute](CONTRIBUTING.md) · [Report an issue](https://github.com/moonrunnerkc/tracemantle/issues) · [Changelog](CHANGELOG.md) · [MIT license](LICENSE)
