| 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
- 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.
- 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.
