SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdraft-writing

draft-writing

Writing & research

View repository

Updated 10-16 09:48

About this skill

Draft Writing Skill

Triggers: write draft, draft, section, citation, citation, word count, patch, writing order

Prerequisites

  1. project_action(action="current") Confirm project
  2. concept.md exists and the 🔒 block is non-empty (except when writing concept.md itself)

MCP Tools

Writing

Tool Description
draft_action(action="write") Create/overwrite draft (filename, content, project）
draft_action(action="section") Produce section from notes (topic, notes）
draft_action(action="read") Read draft
draft_action(action="list") List all drafts
draft_action(action="check_order") ⭐ Check writing order and progress (advisory, does not block)

Citations (⚠️ Modifying citations must use draft_action(action="patch"), forbidden replace_string_in_file）

Tool Description
draft_action(action="available_citations") ⚠️ Must call before editing! List available [[citation_key]]
draft_action(action="patch") Partially edit draft, automatically validate wikilinks
draft_action(action="insert_citation") Insert citation at a specific point (filename, target_text, pmid）
draft_action(action="sync_references") Scan [[wikilinks]] to generate References
draft_action(action="count_words") Calculate word count

draft_action(action="patch") vs replace_string_in_file: the draft facade validates citations, automatically fixes formatting, and rejects nonexistent citations.

Automatic snapshots (CONSTITUTION §22 Auditable)

All draft write paths (via draft_action(action="write"|"patch"|"insert_citation"), as well as full-surface legacy verbs) before overwritingautomatically create a snapshot, stored in drafts/.snapshots/。

  • Keep at most 20 snapshots/file, automatically cleaned up
  • Does not depend on git or agent cooperation, triggered purely in the write path
  • Use DraftSnapshotManager（infrastructure/persistence/）

Writing Order (Advisory)

Paper Type Order
original-research Methods → Results → Introduction → Discussion → Conclusion → Abstract
systematic-review Methods → Results → Discussion → Introduction → Conclusion → Abstract
case-report Case Presentation → Discussion → Introduction → Conclusion → Abstract
review-article Introduction → Body → Conclusion → Abstract

Prerequisites: Results requires Methods, Discussion requires Results+Intro, Conclusion requires Discussion, Abstract requires all. draft_action(action="check_order") Generates a warning, does not block. When a warning appears, ask the user whether to continue.

Flow A: Writing a New Section

  1. draft_action(action="check_order") → Confirm prerequisites
  2. validate_for_section(section) → ✅/❌
  3. draft_action(action="read", filename="concept.md") → Extract 🔒 NOVELTY + 🔒 SELLING POINTS
  4. Write with reference to the Section guide below
  5. draft_action(action="count_words")
  6. pipeline_action(action="approve_section", section=section, decision="approve|revise") → User reviews approve/revise (MANDATORY in Phase 5)

Flow B: Citation-Aware Editing

  1. draft_action(action="available_citations") → Obtain available citation keys
  2. draft_action(action="patch", filename=..., old_text=..., new_text=...) → Automatically validate wikilinks
  3. draft_action(action="sync_references", filename=...) → Generate References

🔒 Protected Content

  • The beginning/end of the Introduction must echo 🔒 NOVELTY
  • The Discussion must emphasize each 🔒 SELLING POINTS item one by one
  • The 🔒 block must not be deleted or weakened. The user must be asked before modification

Section Writing Guide

Each guide below has a corresponding Code-Enforced Hook (B9-B16),run_quality_checks(action="writing_hooks") which checks automatically.

Introduction (400-600 words)

Structure (Funnel Model — Hook B12 auto-detects):

  1. Broad Context (1-2 paragraphs): the importance and prevalence of the clinical problem, using specific numbers (incidence, mortality)
  2. Evidence Base (1-2 paragraphs): findings in the current literature, must have [[wikilinks]] citations
  3. Knowledge Gap (1 paragraph): the shortcomings of prior research → corresponds to 🔒 NOVELTY
  4. Study Objective (last paragraph): "This study aimed to..." or "We sought to..."

Tense (Hook B9):

  • Established facts → Present tense（「Diabetes is characterized by...」）
  • Results of previous studies → Past tense（「Smith et al. reported that...」）

Prohibited items:

  • 🚫 "In recent years..." / "With the rapid development of..."
  • 🚫 Starting each paragraph with "Furthermore" / "Moreover" / "Additionally"
  • 🚫 Revealing your own Results in the Introduction (Hook B12 CRITICAL)
  • 🚫 Excessive hedging: "may potentially suggest..." (Hook B15)

Checklist (Agent self-verification):

  • The first paragraph has specific epidemiological figures
  • Has ≥3 citations supporting the Evidence Base
  • Knowledge Gap uses transitional words (however, nevertheless, yet)
  • The last paragraph clearly states the research objective

Methods (800-1200 words)

Structure:

  1. Study Design & Setting: study type, single/multi-center, time frame
  2. Participants: inclusion/exclusion criteria, age, population
  3. Intervention / Exposure: intervention description or exposure definition
  4. Outcomes: Primary + Secondary endpoints, clearly defined
  5. Statistical Analysis: analysis methods, software version, significance threshold

Tense (Hook B9 CRITICAL):

  • All descriptions must use thepast tense（「We enrolled...」「Data were collected...」）
  • 🚫 Do not use the present tense to describe completed method steps

Ethics statement (Hook B14 CRITICAL):

  • ✅ Must include IRB / Ethics committee approval + approval number
  • ✅ Must include an Informed consent statement (or waiver explanation)
  • ✅ If an interventional study: must include Trial registration number (e.g., NCT12345678)

Statistical reporting standards (Hook B8 / B16):

  • All statistical methods used in the Results must be listed in advance in the Methods
  • Events should correspond to the Outcomes definitions in the Methods

Checklist：

  • Study design stated at the outset
  • Inclusion/exclusion criteria clearly listed
  • Statistical methods correspond to all outcome variables
  • Ethics statement + Informed consent present
  • If RCT: has descriptions of randomization and allocation concealment

Results (600-1000 words)

Structure:

  1. Participant Flow: number of participants screened→included→analyzed (with CONSORT flow diagram)
  2. Baseline Characteristics: Table 1 description, between-group comparisons
  3. Primary Outcome: primary results + effect size + 95% CI + p-value
  4. Secondary Outcomes: secondary results reported by group
  5. Adverse Events / Safety: if applicable

Tense (Hook B9 CRITICAL):

  • All result descriptions must use thepast tense（「was observed」「were significantly higher」）

Objectivity (Hook B11 CRITICAL — the most common Reviewer comment):

  • ✅ Results report only observed data and statistical results
  • 🚫 No interpretive language: "suggesting that", "indicating", "demonstrating that"
  • 🚫 No subjective descriptors: "interestingly", "surprisingly", "remarkably"
  • 🚫 No speculation: "may be due to", "possibly reflects", "we believe"
  • → Interpretation belongs in the Discussion

Statistical reporting (Hook B16):

  • ✅ Report exact p-values (p = 0.032), not just p < 0.05
  • 🚫 No "p = 0.000" → should be written as p < 0.001
  • ✅ Effect sizes (OR, HR, RR, MD, Cohen's d) must be accompanied by a p-value
  • ✅ All effect sizes should be accompanied by a 95% CI

Checklist：

  • Has clear participant screening numbers
  • Primary outcome has effect size + 95% CI + p-value
  • No interpretive language (B11 PASS)
  • All in past tense
  • Figures and tables have corresponding narrative in the main text

Discussion (1000-1500 words)

Structure (Hook B13 auto-detection):

  1. Main Findings (Paragraph 1): Restate the main findings (including 🔒 SELLING POINTS)
  2. Literature Comparison (2-3 paragraphs): Compare with previous studies, with [[wikilinks]] ≥3
  3. Mechanism / Explanation (1 paragraph): Possible mechanisms or clinical interpretation
  4. Clinical Implications (1 paragraph): Clinical practice implications or future directions
  5. Limitations (1 paragraph, Hook B13 CRITICAL): Honestly acknowledge study limitations
  6. Conclusion (Last 1-2 sentences): Concisely restate the core findings

Limitations paragraph (required — Hook B13 triggers CRITICAL):

  • ✅ Must include "limitation" / "weakness" / "shortcoming"
  • ✅ Mention at least 2-3 specific limitations: study design, sample size, follow-up duration, selection bias, etc.
  • ✅ For each limitation, explain why it does not affect the main conclusion (or acknowledge the possible direction of impact)

Hedging control (Hook B15):

  • Discussion may use hedging in moderation (may, might, could)
  • But density exceeding 6/1000 words → CRITICAL (manuscript appears uncertain)
  • Target: below 3/1000 words

Prohibited items:

  • 🚫 Repeating background knowledge already mentioned in the Introduction
  • 🚫 Introducing new data in the Discussion (belongs in Results)
  • 🚫 Overextending conclusions beyond what the study design can support

Checklist：

  • First paragraph restates main findings
  • Has ≥3 comparison citations with previous literature
  • Limitations paragraph exists and is specific
  • Has clinical implications or future directions
  • Conclusion is concise and does not exceed the scope supported by the data

Abstract (250-350 words)

Structure (Structured):

  1. Background (2-3 sentences): Problem + gap + objective
  2. Methods (3-4 sentences): Design, participants, main measurements
  3. Results (3-5 sentences): Main results + key numbers + p-values
  4. Conclusions (1-2 sentences): Core findings + significance

Rules:

  • ✅ The Abstract is a standalone mini-paper, understandable without relying on the main text
  • ✅ Numbers in the Abstract must be completely consistent with the Results
  • 🚫 Do not cite literature in the Abstract
  • 🚫 Do not use undefined abbreviations (abbreviations in the Abstract must be redefined)

Code-Enforced Writing Hooks Reference Table

Hook Name Trigger Timing Severity Key Checks
B9 Section Tense POST-WRITE CRITICAL/WARN Methods/Results past tense
B10 Paragraph Quality POST-WRITE WARN/INFO Paragraph length, single-sentence paragraphs
B11 Results Objectivity POST-SECTION CRITICAL Results prohibit interpretive language
B12 Intro Funnel POST-SECTION CRITICAL/WARN Introduction funnel structure + prohibit revealing results
B13 Discussion Structure POST-SECTION CRITICAL Limitations must exist
B14 Ethical Statements POST-SECTION CRITICAL IRB + Consent + Trial Reg
B15 Hedging Density POST-WRITE CRITICAL/WARN may/might/could density
B16 Effect Size POST-SECTION CRITICAL/WARN p-value format + effect size + CI

Usage:run_quality_checks(action="writing_hooks", hooks="B9,B11,B13") or run_quality_checks(action="writing_hooks", hooks="post-section")

Wikilink format

✅ [[author2024_12345678]] → auto-repair [[12345678]] → [[author2024_12345678]]