# trailmark-summary

Gives a quick structural overview of a codebase: detected languages, entry point count, and dependencies, using the Trailmark tool.

Skill by Trail of Bits. Category: Code quality.

## Install

Project (for this project only):

```sh
npx skills add trailofbits/skills --skill trailmark-summary
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add trailofbits/skills --skill trailmark-summary -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.
- Runs shell commands: Its steps run shell commands in your terminal.

## Security audits

- Gen Agent Trust Hub: Warn
- Socket: Pass
- Snyk: Pass
- ZeroLeaks: Pass

Installs: 3616. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/trailofbits/skills/trailmark-summary)

## Source

[Open the source](https://github.com/trailofbits/skills/tree/HEAD/plugins/trailmark/skills/trailmark-summary). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: trailmark-summary
description: "Runs a Trailmark summary analysis on a codebase. Returns auto-detected languages, entry point count, and dependency list. Use when vivisect or galvanize needs a quick structural overview. Triggers: trailmark summary, code summary, structural overview."
allowed-tools: Bash Read Grep Glob
---

# Trailmark Summary

Runs `trailmark analyze --language auto --summary` on a target directory.
This is a v0.2-safe workflow; do not require Trailmark 0.4.0 just to produce a
summary.

## When to Use

- Vivisect Phase 0 needs a quick structural overview before decomposition
- Galvanize Phase 1 needs detected languages and entry point count
- Quick orientation on an unfamiliar codebase before deeper analysis

## When NOT to Use

- Full structural analysis with all passes needed (use `trailmark-structural`)
- Detailed code graph queries (use the main `trailmark` skill directly)
- You need hotspot scores or taint data (use `trailmark-structural`)

## Rationalizations to Reject

| Rationalization | Why It's Wrong | Required Action |
|-----------------|----------------|-----------------|
| "I can read the code manually instead" | Manual reading misses parser-based language detection, dependency data, and entry point enumeration | Install and run trailmark |
| "Language detection doesn't matter" | Wrong language selection produces empty or partial analysis | Use Trailmark's parser-based detection or `--language auto` |
| "Partial output is good enough" | Missing any of the three required outputs (detected languages, entry points, dependencies) means incomplete analysis | Verify all three are present |
| "Tool isn't installed, I'll skip it" | This skill exists specifically to run trailmark | Report the installation gap instead of skipping |

## Usage

The target directory is passed via the `args` parameter.

## Execution

**Step 1: Check that trailmark is available.**

```bash
trailmark analyze --help 2>/dev/null || \
  uv run trailmark analyze --help 2>/dev/null
```

If neither command works, report "trailmark is not installed"
and return. Do NOT run `pip install`, `uv pip install`,
`git clone`, or any install command. The user must install
trailmark themselves.

Optionally record the version if the installed build supports it:

```bash
trailmark --version 2>/dev/null || uv run trailmark --version 2>/dev/null || true
```

Do not fail if the version command is missing; older v0.2.x builds may still
support the summary workflow.

**Step 2: Detect languages with Trailmark's parse API.**

```bash
python3 - "{args}" <<'PY'
import json
import sys

try:
    from trailmark.parse import detect_languages  # canonical location since 0.3.x
except ModuleNotFoundError:
    # v0.2.x predates trailmark.parse; the same function lives in query.api
    from trailmark.query.api import detect_languages

print(json.dumps(detect_languages(sys.argv[1])))
PY
```

If the import fails, rerun the same snippet with `uv run --with trailmark python - "{args}"`.
If the result is `[]`, report "Trailmark found no supported languages under
target" and return.

**Step 3: Run the summary with auto-detection.**

```bash
trailmark analyze --language auto --summary {args} 2>&1 || \
  uv run trailmark analyze --language auto --summary {args} 2>&1
```

**Step 4: Verify the output.**

The output must include ALL THREE of:
1. Detected languages from Step 2
2. `Entrypoints:` line from the summary output
3. `Dependencies:` line from the summary output

If any are missing, report the gap. Do not fabricate output.

Return the detected language list plus the full Trailmark summary output.
If a version string was available, include it in the returned metadata.
````

- Previous: [crypto-protocol-diagram](https://syn4pse.dev/terminal/crypto-protocol-diagram.md)
- Next: [trailmark-structural](https://syn4pse.dev/terminal/trailmark-structural.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
