agentleFS
LaansDoleLaansDole/my-hermes-skills/skills/productivity/writing-reports/SKILL.md

writing-reports

Skill3 starsChanged 10 days agoMITView on GitHub

Use when the user asks for a report, research write-up, benchmark/model/tool comparison, or any 'give me the report' request.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Not for: one-line answers, PR descriptions (pr skills), Covidence verdicts (own skill).

    line 24
  2. Distinctive:

    Compute: All derived metrics (blends, ratios, per-point costs) calculated in Python, never mentally.

    line 29
  3. Very specific:

    When the caller supplies the data and forbids web search, the ≥2-source cross-check is waived — but the Method line must say Inputs as …

    line 50
  4. Very specific:

    Every report file lands in ~/Projects/auto-learn-for-me/reports/YYYY-MM/ as YYYY-MM-DD-<slug>.md (e.g.

    line 54
  5. Distinctive:

    When a report is requested in chat, still write the file (chat is ephemeral.

    line 56
  6. Distinctive:

    If a report was written elsewhere (a work repo, another machine path), move or symlink it into the library and note the original location …

    line 57

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing Reports

Overview

A report is a decision document: verdict first, evidence second, provenance always. Every report ships in two parts: a dated markdown file (full) + a short chat lead (verdict + key table + file path).

When to Use

  • "give me a report" / research-then-writeup requests
  • Benchmark, model, tool, price, or data comparisons

Not for: one-line answers, PR descriptions (pr skills), Covidence verdicts (own skill).

Method

  1. Gather. SearXNG search first (if :8888 down → restart-first rule, skill selfhosted-search). Scrape sources with curl + parse programmatically. Never single-source a number — cross-check prices/benchmarks in ≥2 independent sources (waived only in Trusted-Input Mode). Date-stamp: fetched data gets its fetch date, computed-only data gets the compute date.
  2. Compute. All derived metrics (blends, ratios, per-point costs) calculated in Python, never mentally. State the formula next to the column (e.g. "blend = 3:1 in:out").
  3. Write the file. ~/Projects/auto-learn-for-me/reports/YYYY-MM/YYYY-MM-DD-<slug>.md (see Report Filing) — skeleton in references/report-template.md.
  4. Deliver. Chat = verdict + the one key table + file path. If the user wants it in Word → plain text, ALL-CAPS headers, no markdown, piped to pbcopy.

Report Structure

# Title → metadata bullet list (Date / Scope / Method — one - **Label:** value bullet each) → Verdict (first sentence of prose) → tables → numbered findings → caveats → numbered references. Inline [n] citations throughout. Fill the template; don't improvise structure.

Hard Rules

  • Verdict in the first sentence of prose. The metadata block comes first in the file (template order); the Verdict section opens with the decision — no "Executive summary" preamble, no restating the request.
  • Every number has a source or a formula. Measured vs vendor-claimed vs derived — say which. Caller-supplied figures are labeled caller-supplied (not vendor-claimed).
  • Assumptions are labeled ASSUMPTION: inline where used, never hidden in a footer.
  • Cite inline, number the references. Every sourced claim, number or quote carries an inline marker right after it: [n], or [n, m] for several sources. The ## References section lists each source once, numbered in order of first citation: [n] Title: <URL>. That is the title (with publisher and date when useful), then the URL in angle brackets. Don't use bare URLs, and don't invent titles for unfetched URLs (use [n] [unfetched — <URL>]). The docs site turns each marker into a linked superscript with a hover preview of the title, and links each reference back to its citations. Uncited references and citations with no matching reference are both errors: check that the set of cited numbers equals the set of reference numbers before filing.
  • No --- separators between sections. Headings separate sections. Rules drawn between every section make a report harder to read.
  • No invented scenarios. Illustrative math (e.g. monthly cost) must be flagged as an estimate with its basis.
  • Chat lead follows ADHD shape: answer first, tables over prose, no preamble/recap (skill i-have-adhd).
  • Filing is the default. Skip the file only when the caller explicitly forbids writing files; then say in the reply that the report is chat-only and unfiled.

Trusted-Input Mode

When the caller supplies the data and forbids web search, the ≥2-source cross-check is waived — but the Method line must say Inputs as supplied by caller, not independently verified, and Caveats carries the single-source risk. Never silently skip verification.

Report Filing (dated reports library)

Every report file lands in ~/Projects/auto-learn-for-me/reports/YYYY-MM/ as YYYY-MM-DD-<slug>.md (e.g. 2026-09-08-commandcode-cost-efficiency.md) — this folder is the running library of past reports, so a later "that report we did on X" resolves to a file, not session memory.

  • When a report is requested in chat, still write the file (chat is ephemeral; the file is the artifact).
  • If a report was written elsewhere (a work repo, another machine path), move or symlink it into the library and note the original location in its metadata block.
  • Need something from an old report? ls reports/YYYY-MM/ or search by slug before re-researching.

Common Mistakes

MistakeFix
"Executive summary" heading before the verdictVerdict IS the first line
Bare URL in referencesNumbered [n] Title: <URL> per source
Sources listed but never cited in the textInline [n] after each sourced claim; cited set = reference set
Metric column with no formulaFormula beside the column header or footnote
Unlabeled invented usage scenarioASSUMPTION: inline + basis
Full report dumped into chatFile + short lead; chat table ≤ 10 rows
Report only in chat, no fileChat is ephemeral — file it: reports/YYYY-MM/YYYY-MM-DD-<slug>.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.