Skip to content

Commit 4716f2e

Browse files
ZimoLiaoZimoLiao
authored
Merge pull request #67 from ZimoLiao/issue-55-2
feat: organize academic writing workflows
2 parents 3645c13 + c5e9a3e commit 4716f2e

15 files changed

Lines changed: 695 additions & 10 deletions

File tree

‎.claude/skills/academic-writing/SKILL.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
name: academic-writing
3+
description: Use when the user needs help choosing or organizing the right academic-writing workflow by deliverable, writing stage, or final document type such as review article, paper section, rebuttal, PPT, poster, or technical report.
4+
version: 1.0.0
5+
author: ZimoLiao/scholaraio
6+
license: MIT
7+
tags: ["academic", "writing", "router", "workflow", "report"]
8+
---
9+
# Academic Writing Router
10+
11+
Route academic-writing requests to the right specialized skill with minimal overlap.
12+
13+
## Purpose
14+
15+
This skill is the **entry point** for users who know what they want to produce, but do not know which writing workflow to use.
16+
17+
Do not duplicate the full instructions of the downstream skills. Your job is to:
18+
- identify the target deliverable
19+
- identify the current writing stage
20+
- select the right specialized skill or skill combination
21+
- explain the route briefly, then continue with that workflow
22+
23+
## Route By Deliverable
24+
25+
| User wants | Route |
26+
|------------|-------|
27+
| 文献综述 / survey / review article | `/literature-review` |
28+
| 论文具体章节（Introduction / Method / Results / Discussion / Conclusion） | `/paper-writing` |
29+
| 审稿回复 / rebuttal / response letter | `/review-response` |
30+
| 研究空白分析 / 选题调研 | `/research-gap` |
31+
| 语言润色 / 去 AI 味 / 风格迁移 | `/writing-polish` |
32+
| 引用真实性检查 | `/citation-check` |
33+
| 正式 Word 报告 | 写作 skill + `/document` |
34+
| 汇报 PPT / 答辩幻灯片 | 写作 skill + `/document` |
35+
| 海报内容包 | `/poster` |
36+
| 专题/技术调研报告 | `/technical-report` |
37+
38+
## Route By Writing Stage
39+
40+
| Stage | Route |
41+
|-------|-------|
42+
| 还没确定应该用哪个 skill | 留在本 skill，先做任务分流 |
43+
| 已有论文集合，需要组织叙述 | `/literature-review` |
44+
| 已有研究内容，需要写论文段落 | `/paper-writing` |
45+
| 已收到审稿意见 | `/review-response` |
46+
| 还在找空白和方向 | `/research-gap` |
47+
| 只需要修语言 | `/writing-polish` |
48+
| 快交稿了，要核验引用 | `/citation-check` |
49+
| 需要交付 DOCX / PPTX | `/document` |
50+
51+
## Deliverable Guidance
52+
53+
### PPT / Beamer
54+
55+
- 当前一等支持的演示文稿交付是 `PPTX`，通过 `/document` 生成和检查。
56+
- 如果用户明确说 `beamer`，先按“演示文稿内容工作流”组织结构、标题、每页要点、图表需求。
57+
- 除非用户明确要求 LaTeX 模板实现，否则默认优先走 `PPTX`，不要假设仓库已经有 beamer 专用后端。
58+
59+
### Poster
60+
61+
- 海报任务优先交给 `/poster`，由它负责 poster 专属的版块和文本密度控制。
62+
- `/poster` 会继续组合 `/literature-review`、`/paper-writing`、`/research-gap`、`/draw`、`/document`。
63+
64+
### Technical Report / Special-Topic Report
65+
66+
- 这类任务优先交给 `/technical-report`，由它负责 audience、结构和建议层组织。
67+
- `/technical-report` 会继续组合 `/literature-review`、`/research-gap`、`/paper-writing`、`/document`。
68+
69+
## Workflow
70+
71+
1. 明确用户最终要交付什么。
72+
2. 判断用户现在处于哪个阶段：选题、搜集、起草、润色、回复、排版交付。
73+
3. 选择一个主 skill；只有在确有必要时才组合多个 skill。
74+
4. 用一句话告诉用户接下来走哪条路线。
75+
5. 转入下游 skill 的工作流，避免在本 skill 中重复实现它们。
76+
77+
## Principles
78+
79+
- **路由优先**：本 skill 负责分流，不负责取代其他写作 skill。
80+
- **最小组合**：能用一个 skill 解决时，不要堆多个。
81+
- **交付物导向**：按用户最终产物组织流程，而不是按内部模块名组织。
82+
- **诚实表达能力边界**：当前一等文档交付是 `DOCX/PPTX/XLSX`；对 `beamer/poster` 用“工作流支持”表述，不要伪装成已有独立后端。
83+
84+
## Examples
85+
86+
用户说："我想做一个给导师汇报的 PPT，但还没想好结构"
87+
→ 先用本 skill 路由到 “汇报 PPT” 工作流，再转 `/document`，必要时补 `/research-gap` 或 `/literature-review`
88+
89+
用户说："帮我写一个技术调研报告"
90+
→ 先判断是偏综述还是偏研究空白分析，然后转 `/literature-review` 或 `/research-gap`，最后如需正式文件再接 `/document`
91+
92+
用户说："我想写 beamer"
93+
→ 先确认是否真的需要 LaTeX beamer；若不是硬要求，默认走演示内容 + `PPTX` 工作流

‎.claude/skills/poster/SKILL.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
name: poster
3+
description: Use when the user needs an academic poster, conference poster, or poster-style visual summary and wants help structuring sections, balancing text and figures, and packaging the result into a practical deliverable workflow.
4+
version: 1.0.0
5+
author: ZimoLiao/scholaraio
6+
license: MIT
7+
tags: ["academic", "writing", "poster", "presentation", "visual"]
8+
---
9+
# Academic Poster Workflow
10+
11+
Create a poster-ready content package without duplicating the full workflows of the other writing skills.
12+
13+
## Purpose
14+
15+
This skill is for **poster-specific organization**:
16+
- define the poster's audience and message
17+
- decide what belongs on the poster and what must be omitted
18+
- convert literature or manuscript content into poster sections
19+
- route figure/layout work to `/draw` and `/document`
20+
21+
Do not treat a poster like a shortened paper. A poster is a **visual argument** with a small number of high-priority claims.
22+
23+
## When To Use
24+
25+
Use this skill when the user wants:
26+
- a conference poster
27+
- a poster-style literature summary
28+
- a visual one-page research overview
29+
- help deciding poster sections, text density, and figure priorities
30+
31+
If the user mainly wants:
32+
- a slide deck: route to `/document`
33+
- a long written report: route to `/technical-report`
34+
- a paper section: route to `/paper-writing`
35+
36+
## Workflow
37+
38+
### 1. Clarify Poster Context
39+
40+
Identify:
41+
- target venue or audience
42+
- poster goal: present a study, summarize a topic, or pitch a direction
43+
- expected size or format if the user knows it
44+
- available materials: workspace papers, manuscript draft, figures, data
45+
46+
### 2. Choose The Content Source
47+
48+
Use one main upstream workflow:
49+
50+
| Situation | Route |
51+
|-----------|-------|
52+
| Poster summarizes a research field | `/literature-review` |
53+
| Poster presents a user's own paper or method | `/paper-writing` |
54+
| Poster motivates a new topic or open problem | `/research-gap` |
55+
56+
### 3. Build A Poster Skeleton
57+
58+
Default sections:
59+
1. Title + one-sentence claim
60+
2. Background / problem
61+
3. Method or comparison frame
62+
4. Key evidence or findings
63+
5. Main takeaway
64+
6. References / contact / QR block if needed
65+
66+
Keep these rules:
67+
- one central claim, not many equal claims
68+
- prefer figures, tables, and short bullets over dense prose
69+
- each section should answer one question only
70+
- remove any paragraph that needs sustained close reading
71+
72+
### 4. Route Assets And Packaging
73+
74+
- Use `/draw` when the poster needs diagrams, cleaned figures, timelines, or concept maps.
75+
- Use `/document` when the result should be packaged into a practical file such as `PPTX` or another layout-friendly deliverable.
76+
- If the user explicitly needs a print-ready poster size, keep the poster structure here, then use `/document` to implement the layout.
77+
78+
## Output Pattern
79+
80+
Recommended outputs inside `workspace/<name>/`:
81+
- `poster-outline.md`
82+
- `poster-copy.md`
83+
- `poster-assets/`
84+
- packaged deliverable from `/document`
85+
86+
## Principles
87+
88+
- **Poster first**: optimize for scanability, not completeness.
89+
- **Visual priority**: text exists to support figures and claims.
90+
- **Claim discipline**: every block must support the poster's main message.
91+
- **Honest scope**: current first-class packaging is via `/document`; do not imply a dedicated poster renderer if none exists.
92+
93+
## Example
94+
95+
用户说："帮我把这个工作区做成一个 conference poster"
96+
→ 用本 skill确定 poster 骨架和主张，再转 `/paper-writing` 或 `/literature-review` 生成文案，必要时接 `/draw` 和 `/document`

‎.claude/skills/technical-report/SKILL.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
name: technical-report
3+
description: Use when the user wants a technical report, topic report, research briefing, or structured investigation document and needs help organizing scope, evidence, recommendations, and final report packaging.
4+
version: 1.0.0
5+
author: ZimoLiao/scholaraio
6+
license: MIT
7+
tags: ["academic", "writing", "report", "survey", "briefing"]
8+
---
9+
# Technical Report Workflow
10+
11+
Create a report-oriented workflow for investigation, synthesis, and recommendation.
12+
13+
## Purpose
14+
15+
This skill handles the cases that are **not quite a paper and not just raw notes**:
16+
- technical survey reports
17+
- topic briefings
18+
- special-topic investigations
19+
- advisor or team-facing research reports
20+
21+
It does not replace the deeper analysis skills. Instead, it decides which analysis path to use and then shapes the result into a report.
22+
23+
## When To Use
24+
25+
Use this skill when the user wants:
26+
- a technical report
27+
- a topic or special-subject report
28+
- a research briefing for a team, supervisor, or project
29+
- a recommendation memo grounded in literature
30+
31+
If the user mainly wants:
32+
- a literature review article: use `/literature-review`
33+
- an open-problem analysis: use `/research-gap`
34+
- a slide deck: use `/document`
35+
36+
## Workflow
37+
38+
### 1. Clarify Report Goal
39+
40+
Identify:
41+
- who the report is for
42+
- whether the report is explanatory, comparative, or decision-support
43+
- whether the user wants conclusions only or also recommendations
44+
- whether the report is meant to stay as Markdown or become a formal DOCX/PPTX deliverable
45+
46+
### 2. Choose The Analysis Backbone
47+
48+
Use one primary path:
49+
50+
| Report type | Route |
51+
|-------------|-------|
52+
| State-of-the-art / what is known | `/literature-review` |
53+
| Open questions / what is missing | `/research-gap` |
54+
| User's own project update or method summary | `/paper-writing` |
55+
56+
### 3. Build A Report Structure
57+
58+
Recommended default structure:
59+
1. Executive summary
60+
2. Scope and question definition
61+
3. Evidence base or literature coverage
62+
4. Comparative analysis
63+
5. Risks, limitations, or disagreements
64+
6. Recommendations / next steps
65+
7. References
66+
67+
Adjust by audience:
68+
- supervisor or PI: prioritize takeaways and decisions
69+
- technical team: prioritize trade-offs, methods, constraints
70+
- self-study memo: prioritize structure and evidence trail
71+
72+
### 4. Package The Deliverable
73+
74+
- Use `/document` when the report should be turned into a formal `DOCX` or presentation.
75+
- Use `/citation-check` before final delivery if the report contains generated author-year citations.
76+
- Use `/export` if the user wants a bibliography bundle alongside the report.
77+
78+
## Output Pattern
79+
80+
Recommended outputs inside `workspace/<name>/`:
81+
- `technical-report-outline.md`
82+
- `technical-report.md`
83+
- `references.bib`
84+
- packaged deliverable from `/document` if requested
85+
86+
## Principles
87+
88+
- **Decision-oriented structure**: reports should help someone act, not only read.
89+
- **Separation of layers**: analysis comes from existing writing/research skills; this skill organizes it into a report.
90+
- **Audience-aware emphasis**: same evidence, different structure for different readers.
91+
- **Honest scope**: packaging is currently routed through `/document`; do not imply a separate report generator backend.
92+
93+
## Example
94+
95+
用户说："帮我写一个这个方向的技术调研报告，给组会用"
96+
→ 用本 skill 先明确 audience 和结构，再转 `/literature-review` 或 `/research-gap` 形成分析主体，最后接 `/document`

‎AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,12 +65,15 @@ Knowledge base management:
6565
- `translate` - When the user wants to translate papers into a target language while keeping Markdown structure, use this skill.
6666

6767
Academic writing:
68+
- `academic-writing` - When the user needs help choosing or organizing the right academic-writing workflow by deliverable or final format (review, paper section, rebuttal, PPT, poster, technical report), use this skill as the router.
6869
- `literature-review` - When the user wants to write a literature review, organize topics, and build a critical narrative, use this skill.
6970
- `paper-writing` - When the user wants to draft concrete paper sections rather than a generic summary, use this skill.
7071
- `citation-check` - When the user is worried about fake citations, wrong author-year pairs, or AI citation hallucinations, use this skill.
7172
- `writing-polish` - When the user wants academic polishing, de-AI-fication, or style transfer, use this skill.
7273
- `review-response` - When the user wants to answer reviewer comments, write a rebuttal, or prepare a point-by-point response, use this skill.
7374
- `research-gap` - When the user wants to identify research gaps and open questions from existing literature, use this skill.
75+
- `technical-report` - When the user wants a technical report, topic report, or research briefing and needs help organizing scope, evidence, recommendations, and packaging, use this skill.
76+
- `poster` - When the user wants an academic poster or poster-style visual summary and needs help structuring sections, balancing text and figures, and packaging the result, use this skill.
7477

7578
Visualization and document generation:
7679
- `draw` - When the user wants to visualize a process, structure, timeline, or concept relationships, use this skill.

‎AGENTS_CN.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,12 +64,15 @@ Skills 定义在 `.claude/skills/` 目录，遵循 [Agent Skills](https://agents
6464
- `translate` — 当用户要把论文翻译到目标语言并保留 Markdown 结构时，用这个 skill。
6565

6666
学术写作：
67+
- `academic-writing` — 当用户还不确定该用哪条学术写作工作流，或任务是按交付物来定义的（综述、论文章节、rebuttal、PPT、海报、技术调研报告等）时，用这个 skill 做总入口和分流。
6768
- `literature-review` — 当用户要写文献综述、组织主题并形成批判性叙述时，用这个 skill。
6869
- `paper-writing` — 当用户要起草论文具体章节而不是泛泛总结时，用这个 skill。
6970
- `citation-check` — 当用户担心引用不实、作者年份不对或 AI 幻觉引用时，用这个 skill。
7071
- `writing-polish` — 当用户要润色学术表达、去 AI 味或做风格迁移时，用这个 skill。
7172
- `review-response` — 当用户要回审稿意见、写 rebuttal 或逐点回复时，用这个 skill。
7273
- `research-gap` — 当用户要从现有文献中识别研究空白和开放问题时，用这个 skill。
74+
- `technical-report` — 当用户要写技术调研报告、专题报告或研究简报，需要组织范围、证据、建议和最终交付结构时，用这个 skill。
75+
- `poster` — 当用户要做学术海报或海报式研究摘要，需要控制版块结构、图文密度和最终交付方式时，用这个 skill。
7376

7477
可视化与文档生成：
7578
- `draw` — 当用户要把流程、结构、时间线或概念关系画出来时，用这个 skill。

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- **Academic writing router** ([#55](https://github.com/ZimoLiao/scholaraio/issues/55)): Added the `academic-writing` skill as a stable top-level entry point that routes users by deliverable and writing stage instead of forcing them to guess among multiple writing skills
13+
- **Deliverable-first writing workflows** ([#55](https://github.com/ZimoLiao/scholaraio/issues/55)): Added lightweight `poster` and `technical-report` skills so conference posters, poster-style summaries, topic reports, and research briefings are first-class workflows rather than implicit combinations of lower-level skills
14+
- **Writing workflow regression coverage**: Added tests for skill frontmatter validity, router references, approximate host-style skill selection, and 11 rounds of documentation-alignment checks across docs, agent instructions, and marketplace metadata
15+
16+
### Fixed
17+
18+
- **Academic writing docs alignment** ([#55](https://github.com/ZimoLiao/scholaraio/issues/55)): Synchronized `docs/guide/writing.md`, `README.md`, `README_CN.md`, `docs/index.md`, `AGENTS.md`, `AGENTS_CN.md`, `CLAUDE.md`, and `clawhub.yaml` around a router-first writing model so poster/report workflows and the academic-writing entry point are discoverable consistently across user and agent surfaces
19+
1020
## [1.3.1] — 2026-04-14
1121

1222
### Added

‎CLAUDE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,12 +65,15 @@ Knowledge base management:
6565
- `translate` - When the user wants to translate papers into a target language while keeping Markdown structure, use this skill.
6666

6767
Academic writing:
68+
- `academic-writing` - When the user needs help choosing or organizing the right academic-writing workflow by deliverable or final format (review, paper section, rebuttal, PPT, poster, technical report), use this skill as the router.
6869
- `literature-review` - When the user wants to write a literature review, organize topics, and build a critical narrative, use this skill.
6970
- `paper-writing` - When the user wants to draft concrete paper sections rather than a generic summary, use this skill.
7071
- `citation-check` - When the user is worried about fake citations, wrong author-year pairs, or AI citation hallucinations, use this skill.
7172
- `writing-polish` - When the user wants academic polishing, de-AI-fication, or style transfer, use this skill.
7273
- `review-response` - When the user wants to answer reviewer comments, write a rebuttal, or prepare a point-by-point response, use this skill.
7374
- `research-gap` - When the user wants to identify research gaps and open questions from existing literature, use this skill.
75+
- `technical-report` - When the user wants a technical report, topic report, or research briefing and needs help organizing scope, evidence, recommendations, and packaging, use this skill.
76+
- `poster` - When the user wants an academic poster or poster-style visual summary and needs help structuring sections, balancing text and figures, and packaging the result, use this skill.
7477

7578
Visualization and document generation:
7679
- `draw` - When the user wants to visualize a process, structure, timeline, or concept relationships, use this skill.

‎README.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,20 @@ Then open the repository in Codex, Claude Code, or another supported agent. In t
6666
| **Federated Discovery** | Cross-library search | Search your main library, exploration libraries, and arXiv from one entry point instead of hopping across tools |
6767
| **AI-for-Science Runtime** | Use scientific software more accurately | Use scientific software against official documentation at runtime instead of guessing commands and parameters |
6868
| **Extensible Tool Onboarding** | Keep adding the tools that matter | As new scientific tools and workflows become important, the system can keep expanding |
69-
| **Academic Writing** | AI-assisted writing | Literature review, paper sections, citation check, rebuttal, and gap analysis — with every citation traceable to your own library |
69+
| **Academic Writing** | AI-assisted writing | Router-first workflows for literature review, paper sections, citation check, rebuttal, gap analysis, poster packages, and technical reports — with every citation traceable to your own library |
70+
71+
For writing tasks, start with the router-style writing entry when the deliverable is clear but the workflow is not. The current writing stack is organized around:
72+
73+
- `academic-writing`: route by deliverable and writing stage
74+
- `literature-review`: long-form review and survey writing
75+
- `paper-writing`: manuscript sections and paper-focused drafting
76+
- `review-response`: rebuttal and response-letter workflows
77+
- `research-gap`: gap analysis and open-question reports
78+
- `technical-report`: technical briefings and topic reports
79+
- `poster`: poster-oriented content packaging
80+
- `document`: final DOCX / PPTX packaging
81+
82+
See [`docs/guide/writing.md`](docs/guide/writing.md) for the full writing map.
7083

7184
## Works With Your Agent
7285

0 commit comments

Comments
 (0)