Validate agent skills and check the evidence behind a release.
CLI reference · Report a bug or request a feature
About the project
TraceMantle is a Python CLI and library for checking agent skill bundles before they are committed or released. It provides:
- Skill validation: checks
SKILL.mdfrontmatter, file references, size limits and compatibility advice against the Agent Skills specification. - Bundle tracking: hashes skill files and packaged resources so helper changes are detected too.
- Evidence checks: imports evaluator results and compares bundles against trusted policies. Missing, stale or incompatible evidence blocks the gate.
TraceMantle analyzes files; it does not execute skills or evaluators. Static checks and imported model judgments do not prove that a skill works in a live agent.
Getting started
Requires Python 3.10 or later. Install in a virtual environment:
python -m venv .venv
source .venv/bin/activate
python -m pip install tracemantle==1.6.1
tracemantle --version
Version 1.6.1 corrects dependency discovery across Markdown headings and rejects numeric overflow in evidence imports. See the changelog and implementation ledger for behavior and verification.
On Windows PowerShell, activate with .venv\Scripts\Activate.ps1. Replacing SkillCheck? Follow the migration guide before installing.
Usage
Validate a skill, scan a directory, or inspect a bundle:
tracemantle path/to/SKILL.md
tracemantle path/to/skills/ --strict --format json
tracemantle path/to/SKILL.md --analyze-graph
tracemantle manifest path/to/skill --format json
Validation exits 0 when it passes and nonzero on errors; --strict also fails on warnings. Text, JSON and GitHub annotation output are supported.
For release evidence, use import-evidence and compare with a trusted base revision and approved evidence. The evidence workflow covers setup, supported imports and runnable examples.
Configure defaults in tracemantle.toml or [tool.tracemantle] in pyproject.toml. Explicit CLI flags take precedence. Token counting uses an offline estimate by default; optional tiktoken counting must be selected explicitly.
See the CLI and configuration reference, compatibility profiles and input limits for details.
Integrations
Use the composite GitHub Action pinned to a release:
- uses: moonrunnerkc/tracemantle@v1.6.1
with:
path: skills/
Action inputs control validation and reporting. Versions before 1.6.0 contain the older SkillCheck implementation. A pre-commit hook, Python API and installed skill are also included.
Contributing
1407 tests cover validation, CLI integrations, bundle identity and evidence checks. CI runs Python 3.10 through 3.13 on Linux, macOS and Windows, plus optional-tokenizer and clean package-install checks.
See CONTRIBUTING.md for development setup and verification. Submit fixes through pull requests; use issues for bugs and proposals. Changes are recorded in the changelog.
License and contact
MIT. Maintained by moonrunnerkc, Aftermath Technologies Ltd.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file tracemantle-1.6.1.tar.gz.
File metadata
- Download URL: tracemantle-1.6.1.tar.gz
- Upload date:
- Size: 479.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bc755e358264b578bfbc387e1d6f2a30c5af81e1663501680f511493a6953b0c
|
|
| MD5 |
831463917382d79ac3154ee1c00af28d
|
|
| BLAKE2b-256 |
6d49214d7f67a2cbc7003a8f6c39565b8cd751c24c4e91b867009cc1d17fd9da
|
Provenance
The following attestation bundles were made for tracemantle-1.6.1.tar.gz:
Publisher:
release.yml on moonrunnerkc/tracemantle
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
tracemantle-1.6.1.tar.gz -
Subject digest:
bc755e358264b578bfbc387e1d6f2a30c5af81e1663501680f511493a6953b0c - Sigstore transparency entry: 2822423471
- Sigstore integration time:
-
Permalink:
moonrunnerkc/tracemantle@4a502e7f381b6eadf57726285adfd82569461308 -
Branch / Tag:
refs/tags/v1.6.1 - Owner: https://github.com/moonrunnerkc
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4a502e7f381b6eadf57726285adfd82569461308 -
Trigger Event:
push
-
Statement type:
File details
Details for the file tracemantle-1.6.1-py3-none-any.whl.
File metadata
- Download URL: tracemantle-1.6.1-py3-none-any.whl
- Upload date:
- Size: 147.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
93d3bec4201319bd6769482de6cf592372f08915ce164bffb4f7d3cefc7348f6
|
|
| MD5 |
49f7eeb51f8ae21bb62fc6b6ea3aa56a
|
|
| BLAKE2b-256 |
9f883ba58cf9224b7161d5bd85acdcbf2cc86f65c8bf8bb59f838d6c19dd3b70
|
Provenance
The following attestation bundles were made for tracemantle-1.6.1-py3-none-any.whl:
Publisher:
release.yml on moonrunnerkc/tracemantle
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
tracemantle-1.6.1-py3-none-any.whl -
Subject digest:
93d3bec4201319bd6769482de6cf592372f08915ce164bffb4f7d3cefc7348f6 - Sigstore transparency entry: 2822423495
- Sigstore integration time:
-
Permalink:
moonrunnerkc/tracemantle@4a502e7f381b6eadf57726285adfd82569461308 -
Branch / Tag:
refs/tags/v1.6.1 - Owner: https://github.com/moonrunnerkc
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4a502e7f381b6eadf57726285adfd82569461308 -
Trigger Event:
push
-
Statement type:
