version: "1.0.0" name: document-insights description: "Analyze a text document and produce an insights report that pairs EXACT, code-computed metrics (word/character/sentence counts, reading time) with an LLM's interpretive read (sentiment, one-line summary, key themes). Use when you need a grounded document summary where the numbers must be correct, not estimated. Triggers: 'analyze this document', 'document insights', 'sentiment and word count', 'summarize with stats'." metadata: author: Daniel Zivkovic version: 0.1.0

Document Insights

This skill demonstrates the core idea of an Agent Skill: pair DETERMINISTIC code (exact facts an LLM cannot reliably compute) with NON-DETERMINISTIC LLM reasoning (judgment an LLM is good at), and keep the two clearly separated in the output.

How to run this skill

1. Deterministic step - run scripts/analyze.py <input-file>. It returns a JSON object

of exact metrics: word_count, char_count, char_count_no_spaces, line_count, sentence_count, avg_words_per_sentence, reading_time_min, longest_word. These numbers are ground truth. Never let the LLM recompute or "estimate" them.

1. Non-deterministic step - ask the model for an interpretive read of the document:

overall sentiment (positive / neutral / negative) with a one-phrase justification, a single-sentence summary, and 2-3 key themes. The model must ground its answer in the document text and may reference the exact metrics from step 1 (e.g. "a short 42-word note"), but must never invent or restate counts as if it computed them.

Output contract

Produce markdown with two clearly-labeled sections so a reader can see the seam:

• Metrics (computed by code - exact) - a table of the numbers from analyze.py.
• Reading (interpreted by the LLM) - sentiment, one-sentence summary, key themes.

Use hyphens, not em-dashes. Keep it concise.

Why this split matters

An LLM asked "how many words is this?" will guess, and often guess wrong. analyze.py counts them exactly. Conversely, code cannot judge tone; the LLM can. The skill gets the best of both by letting each do what it is good at - and by labeling which is which, the output never passes an LLM guess off as a hard fact.