Using markit

Using Markit

Use this skill to run markit reliably in terminal-based agent workflows.

Scope

• Convert known files and known URLs to markdown.
• Use deterministic output modes for downstream automation.
• Troubleshoot common failures.

Do not cover plugin authoring, provider authoring, or onboarding context files unless the user explicitly asks.

Non-goals

• Open-web discovery, ranking, or source-finding.
• Recency-filtered/domain-filtered research workflows.
• Interactive browser automation workflows (click/fill/login/stateful navigation).
• DOM action tasks that depend on browser node IDs.

Defaults

1. Prefer the global markit command.
2. If markit is missing, install globally with npm install -g markit-ai.
3. Use --json when the result will be parsed or used for branching decisions.
4. Use -q when raw markdown should be piped/copied as-is.
5. Do not mutate config/provider settings unless the user asks.
6. Do not run markit onboard.

Workflow

1. Validate source and intent

   • Identify source type: local file, URL, or stdin.
   • For binary formats (PDF, DOCX, images, audio), prefer file paths over stdin.
   • Confirm whether output should be parsed (--json) or emitted as markdown (-q).
   • If the user needs source discovery first (not conversion of known sources), stop and request specific URLs or files.

2. Preflight command availability

   • Check tool presence:
     • markit --version
   • If missing:
     • npm install -g markit-ai
     • Re-run markit --version

3. Run conversion with the correct mode

   • Structured mode:
     • markit <source> --json
   • Raw markdown mode:
     • markit <source> -q
   • Write to file:
     • markit <source> -o <output.md>
   • URL conversion:
     • markit https://example.com/article -q

4. Handle result deterministically

   • In --json mode, read:
     • success
     • markdown (or error)
     • title when present
   • If writing to file (-o), verify success from command exit/output.

5. Recover from failures

   • Unsupported format:
     • Run markit formats and choose a supported input path.
   • File not found:
     • Recheck path and working directory.
   • URL fetch failure:
     • Retry once; then report status and source URL.
   • AI description/transcription missing:
     • Continue with non-AI extraction and report missing provider/key setup.

Output mode policy

• Choose --json when you need reliable machine parsing.
• Choose -q when markdown is the final artifact or will be piped.
• Avoid plain human mode in automated chains unless the user asks for human-readable terminal output.

AI features (optional, only when requested)

Use for image description and audio transcription.

• OpenAI provider (default) supports image description + transcription.
• Anthropic provider supports image description (no transcription in current built-in provider).

Typical setup:

export OPENAI_API_KEY=sk-...
markit photo.jpg -q
markit recording.mp3 -q

Prompt focus for images:

markit receipt.jpg -p "Extract all line items and prices as a table" -q

Examples

Input: Convert a PDF and parse result in an automated flow. Command: markit report.pdf --json Output: JSON with success, source, optional title, and markdown (or error on failure).

Input: Convert a DOCX and pass raw markdown to another tool. Command: markit document.docx -q Output: Markdown only (no extra decoration).

Input: Convert a webpage to markdown. Command: markit https://example.com -q Output: Markdown extracted from fetched page content.

Input: Convert slides and persist the result. Command: markit slides.pptx -o slides.md Output: slides.md written to disk; command success confirms write.

Input: Confirm whether a format is supported before conversion. Command: markit formats Output: List of built-in and plugin-provided formats.

Guardrails

• Prefer explicit file paths for binary documents.
• Do not assume AI keys exist; detect and degrade gracefully.
• Keep conversion steps idempotent and reproducible.
• Report exact failing command and error when conversion fails.

CLI modes and failure handling

Deterministic output modes

Use --json when downstream logic parses fields like success, markdown, title, or error.

markit <source> --json

Use -q when raw markdown is the final artifact or passed to another command.

markit <source> -q

Typical commands

# Local file to markdown
markit report.pdf -q

# URL to markdown
markit https://example.com/article -q

# Write result to file
markit slides.pptx -o slides.md

# Check supported formats
markit formats

Failure triage

1. Verify CLI availability:

   markit --version
   

2. If missing, install globally:

   npm install -g markit-ai
   

3. For unsupported formats, check markit formats and pick a supported source.

4. For file errors, re-check absolute/relative path and current working directory.

5. For URL failures, retry once, then surface the failing URL and command output.

6. For missing AI provider keys, continue with non-AI extraction where possible.