huashu-report: an agent skill that encodes how top-tier institutions actually lay out research

The gap huashu-report is aimed at: agents that dump search results into a document

Ask a general-purpose agent for an industry report and you usually get a long document assembled from search results. The structure is improvised, the chart captions restate the axis labels, and nothing in the layout signals which numbers are sourced and which are inferred. huashu-report targets that specific failure. It is an Agent Skill, not an application: a set of text conventions plus three Python files that an agent loads before writing.

The audience is narrow and concrete. It is for people who already run reports through an agent and want the output to look like something a research institution would publish: industry reports, white papers, annual surveys, data insights, and arXiv papers. The README is explicit that single articles, slide decks, and presentation scripts are out of scope. That boundary matters, because the skill's whole value is in conventions that only apply to long-form research documents.

Where the rules come from: 42 PDFs and a 41-report quantitative baseline

The distinguishing feature of this project is provenance. The conventions were not written from intuition. According to the README, the author downloaded 42 PDFs from institutions including Stanford HAI, McKinsey, BCG, OpenAI, Anthropic, PwC, Deloitte, the World Bank, and the Reuters Institute in August 2026, then two more later. Because the World Bank WDR overview booklet and the main text are two files of the same report, the quantitative baseline counts 41 distinct reports. The measured anatomy lives in corpus/anatomy.json, and the source list with institution, date, page count, official link and licence status lives in corpus/samples.md.

The repository deliberately does not ship the PDFs, which total roughly 234MB. That is a defensible call for a skill repository people clone into an agent, and it also means the baseline is auditable only at the level of aggregate numbers, not the underlying pages. If you want to verify a specific claim about chart titles or colour usage, you would need to re-download the sources yourself from the links in samples.md.

The README highlights three findings it calls counterintuitive. Body text is near-black in 40 of the 41 reports, with brand colour occupying a median 2.8% of body characters. Chart titles state the conclusion rather than the topic. And top-tier reports include a section that argues against their own conclusions. Whether or not you agree with the framing, these are the kind of claims that come with a number attached, which is more than most style guides offer.

Four roles, six report archetypes, eight chart types: the mechanism inside SKILL.md

The skill's operating model is role sequencing. Instead of one pass that writes a document, the agent works through four roles in order: researcher, editor, information designer, and data visualisation specialist. SKILL.md holds the identity, three questions the agent must answer before starting, and a selection table for six report archetypes. The references directory then supplies the detail for each stage.

Structure skeletons for the six archetypes are in references/结构骨架.md, sentence-level conventions such as how to mark data provenance and how to hedge claims are in references/行文.md, and references/研究深度.md describes a three-layer value model (organise, explain mechanism, position against the literature) along with what should not appear in a report at all. The visual side is split across references/视觉系统.md for the typographic system, references/视觉方向库.md for colour and style direction, and references/图表模式库.md, which maps each of the eight chart types to the comparison it suits.

The production side is where the Python lives. assets/chart.py is an inline SVG library covering the eight chart types and handling negative values. assets/render.py renders output, back-fills table-of-contents page numbers, and runs mechanical self-checks. references/生产流水线.md describes a three-file architecture (data table, generator, renderer) and lists eight specific pitfalls. The README's advice on these two Python files is blunt: copy and reconfigure them rather than rewriting them.

One editorial rule stands out because it is stated as a single test rather than a list. When deciding whether a passage stays, delete the sentence and ask whether the reader's judgement of the research conclusion would change. If not, it is a work log and should be cut. The README applies the same test to itself: sample frames, inclusion and exclusion criteria, and definitional consistency are methodology and must be written; how a tool was installed or where a script errored is engineering record and should not.

Installing huashu-report into a Claude Code skills directory

The skill is plain text plus three Python files and depends on no service. The README gives a clone into the Claude Code skills directory as the first option.

# Claude Code
git clone https://github.com/alchaincyf/huashu-report ~/.claude/skills/huashu-report

After cloning, the skill directory should contain SKILL.md, references/, assets/ and corpus/ at the top level, matching the repository layout. If you run more than one agent and want them to share a single skill pool, the README gives a second target path.

# shared skill pool for multiple agents
git clone https://github.com/alchaincyf/huashu-report ~/.agents/skills/huashu-report

There is no separate install step and no build. The README also notes that you can zip the whole directory and upload it as a custom skill in products that support that, citing Doubao's skill upload flow as one that works and runs the production pipeline end to end.

Triggering is implicit. The README states that you do not need to invoke the skill by name; a request such as producing a research report or a white paper on a topic is enough. A first useful exercise is to ask for a report on a subject you already know well and then check the output against the conventions in references/图表模式库.md and references/视觉系统.md, since those are the parts a general-purpose agent will not reproduce on its own.

Where huashu-report is the wrong tool

The README's own boundary list is the place to start. Single articles, slide decks, and presentation scripts are explicitly out of scope, and the related search interest in slide output does not change that: there is no slide archetype in the six.

The second limitation is linguistic. The conventions were extracted from English-language institutional reports, and the README states that Chinese-language writing habits need a separate pass. The references are written in Chinese, so a Chinese-speaking user may find the guidance readable while the underlying stylistic norms still come from English source documents. Treat the Chinese output as unvalidated by this corpus.

The third is domain skew. The 41-report sample frame leans toward AI and technology, and the README says report conventions in other fields may differ. A clinical research report, a legal memorandum, or a regulatory filing follows different norms, and applying this skill's chart and colour conventions there would be a guess rather than a measured result.

Finally, the corpus is not shipped. If your reason for adopting the skill is to check its quantitative claims, you cannot do that from the clone alone; you need the official links in corpus/samples.md and the willingness to fetch roughly 234MB of PDFs. The README is upfront about this trade-off, but it does mean the baseline's authority rests on the author's measurements rather than on anything a reader can inspect locally.

How huashu-report differs from a generic report-writing prompt

The obvious alternative is a hand-written prompt or a personal style guide pasted into an agent's context. The difference is in what each can support. A prompt encodes what one person believes good reports look like. huashu-report encodes what 41 specific documents were measured to do, with the measurements stored in corpus/anatomy.json and the sources listed in corpus/samples.md. That makes disagreements resolvable: you can check the claim about brand colour usage or chart titling against the listed sources instead of arguing about taste.

The second difference is the tooling. A prompt cannot render an inline SVG chart, back-fill table-of-contents page numbers, or run mechanical self-checks. assets/chart.py and assets/render.py can, and references/生产流水线.md documents eight pitfalls in that pipeline. A prompt-based approach leaves all of that to the agent's discretion each time.

The trade-off runs the other way too. A generic prompt adapts to any document type, including the slides and single articles this skill excludes. It also carries no corpus assumptions, so it does not inherit an AI-and-technology skew or an English-language bias. If your reports fall outside the six archetypes, a well-written prompt is the more flexible instrument, and huashu-report would only add constraints you would then have to work around.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-09-14. There are no retrieved releases, so there is no versioned upgrade path to follow; updates arrive as commits to master. That matters for anyone who edits the references to fit their own conventions, because a git pull can conflict with local changes to files like references/行文.md or references/视觉系统.md. Forking and pulling selectively is the lower-friction arrangement if you plan to modify the conventions.

The corpus is a snapshot by design. It reflects reports published in 2026, and the README describes adding two reports after the initial 42. Institutional conventions drift slowly, but a baseline tied to a fixed set of documents ages with that set. Rebuilding it means re-measuring, and the README points to corpus/anatomy.json as the starting point for anyone who wants to establish a baseline for their own field.

The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained. Nothing in the README addresses attribution for the underlying reports or the reuse of their layouts, and the samples file records licence status per source. That is a question for your own counsel if you intend to reproduce anything resembling the original documents, not something this repository answers.

Editorial conclusion

Adopt huashu-report if you already generate reports inside an agent and want the output to follow conventions that were measured from real institutional documents rather than invented. Skip it if you are producing slide decks, single articles, or Chinese-language reports, since the README says the corpus is English and the conventions come from English institutions. Before committing, open corpus/anatomy.json and check whether its 41-report baseline actually covers your field, because the sample skews toward AI and technology topics.

Frequently asked questions

Official sources

1. alchaincyf/huashu-report on GitHub
2. Issues
3. License: MIT
4. README