Skip to main content
Agent skill

Tracemantle

Validates and scores SKILL.md files against the agentskills.io specification; use when linting skills for cross-agent compatibility, description quality, or capability graph structure.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Tracemantle when an AI agent needs a reusable SKILL.md workflow for this job: Validates and scores SKILL.md files against the agentskills.io specification; use when linting skills for cross-agent compatibility, description quality, or capability graph structure.

When not to use it

Skip Tracemantle when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/tracemantle
# Save SKILL.md to ~/.claude/skills/tracemantle/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/tracemantle/SKILL.md. For a shared project, commit the folder at .claude/skills/tracemantle/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Tracemantle skill for this task: Use Tracemantle when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
54/100
Source signals
70/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

TraceMantle is a local static analyzer for SKILL.md files. It validates frontmatter structure, scores advisory description features, checks file references, and extracts a capability graph from heading and backtick-reference patterns. Run it before committing a skill, plugging it into CI, or publishing to a skill registry.

## Prerequisites

- path - the SKILL.md file or directory to validate - prompt.txt - file path for a saved agent prompt (critique or graph extraction) - response.json - file path for an agent-provided JSON response

## Validate a skill

Pass `path` to `tracemantle` for a full structural check against the agentskills.io specification. Validates name constraints, description quality, body sizing, file references, and cross-agent compatibility. The `validation report` is written to stdout. Exit codes: 0 no errors, 1 errors found, 2 input error (missing file), 3 symbolic passed but semantic critique flagged errors.

```bash tracemantle <path> tracemantle <path> --format json ```

## Review a skill with an agent

tracemantle generates a structured critique prompt for `path` and ingests `response.json` as the agent's reply. Save the emitted prompt to `prompt.txt`. The merged `validation report` combines symbolic diagnostics and semantic findings from the critique.

```bash tracemantle <path> --emit-critique-prompt > prompt.txt ```

Hand `prompt.txt` to your agent. The agent returns JSON. Save the response as `response.json`, then ingest it.

```bash tracemantle <path> --ingest-critique response.json ```

Pass `--critique-agent codex` or `--critique-agent cursor` to select a prompt variant tuned for that platform. The critique JSON schema is identical across all agent targets.

## Extract a capability graph

tracemantle extracts the `capability graph` from heading structure and backtick references in the body of `path`. Use `prompt.txt` for emitted graph prompts and ingest `response.json` from your agent for richer extraction.

Run graph analysis using the heuristic extractor (no agent needed):

```bash tracemantle <path> --analyze-graph ```

For richer extraction, emit the graph prompt, run it through your agent, and ingest the response:

```bash tracemantle <path> --emit-graph-prompt > prompt.txt tracemantle <path> --ingest-graph response.json ```

Print the graph to stdout:

```bash tracemantle <path> --emit-graph tracemantle <path> --emit-graph --format json ```

When both heuristic and agent graphs are available, tracemantle compares them and emits `graph.contradiction.heuristic_disagreement` at error severity for agent-claimed edges that the heuristic does not confirm.

## Check validation history

Append a record to the `validation ledger` for each `--history` run on `path`. The validation history uses immutable per-run records outside the skill bundle, under its parent evidence directory. Legacy history is read without being moved or deleted.

```bash tracemantle <path> --history tracemantle <path> --show-history tracemantle <path> --show-history --format json ```

Each record stores a timestamp, TraceMantle version, bundle/configuration digests, validation modes and per-file results. Comparable prior passing records can produce a history regression warning. Legacy text hashes alone do not establish revision equivalence.

## Compare release evidence

Use `path` with the manifest command to identify skill content and all packaged resources. Import evaluator output into a selected evidence store outside the bundle. Compare baseline and candidate bundles with policy and approved evidence from a trusted base commit. Missing evidence blocks release as unknown; imported model judgments are not proof of observed skill invocation. TraceMantle does not run agents or imported checkers.

```bash tracemantle manifest <bundle> --format json tracemantle compare <baseline> <candidate> --trusted-root <trusted-repo> --base-revision <full-commit-sha> --format json ```

## Outputs

- validation report - diagnostic output written to stdout - capability graph - graph of capabilities, inputs, and outputs extracted from the skill body - validation ledger - immutable validation records outside the evaluated bundle

Intended uses

  • Use Tracemantle when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.