From 8bb14fa1a7bf7e6ee0631db4db9168962edbc31f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adem=20Akdo=C4=9Fan?=
 <53964471+ademakdogan@users.noreply.github.com>
Date: Sun, 5 Apr 2026 05:19:35 +0300
Subject: [PATCH] feat(skills): add academic-paper-review, code-documentation,
 and newsletter-generation skills (#1861)

Add three new public skills to enhance DeerFlow's content creation capabilities:

- **academic-paper-review**: Structured peer-review-quality analysis of
  research papers following top-venue review standards (NeurIPS, ICML, ACL).
  Covers methodology assessment, contribution evaluation, literature
  positioning, and constructive feedback with a 3-phase workflow.

- **code-documentation**: Professional documentation generation for software
  projects, including README generation, API reference docs, architecture
  documentation with Mermaid diagrams, and inline code documentation
  supporting Python, TypeScript, Go, Rust, and Java conventions.

- **newsletter-generation**: Curated newsletter creation with research
  workflow, supporting daily digest, weekly roundup, deep-dive, and industry
  briefing formats. Includes audience-specific tone adaptation and
  multi-source content curation.

All skills:
- Follow the existing SKILL.md frontmatter convention (name + description)
- Pass the official _validate_skill_frontmatter() validation
- Use hyphen-case naming consistent with existing skills
- Contain only allowed frontmatter properties
- Include comprehensive examples, quality checklists, and output templates
---
 skills/public/academic-paper-review/SKILL.md | 289 +++++++++++++
 skills/public/code-documentation/SKILL.md    | 415 +++++++++++++++++++
 skills/public/newsletter-generation/SKILL.md | 343 +++++++++++++++
 3 files changed, 1047 insertions(+)
 create mode 100644 skills/public/academic-paper-review/SKILL.md
 create mode 100644 skills/public/code-documentation/SKILL.md
 create mode 100644 skills/public/newsletter-generation/SKILL.md

diff --git a/skills/public/academic-paper-review/SKILL.md b/skills/public/academic-paper-review/SKILL.md
new file mode 100644
index 000000000..165321cb6
--- /dev/null
+++ b/skills/public/academic-paper-review/SKILL.md
@@ -0,0 +1,289 @@
+---
+name: academic-paper-review
+description: Use this skill when the user requests to review, analyze, critique, or summarize academic papers, research articles, preprints, or scientific publications. Supports comprehensive structured reviews covering methodology assessment, contribution evaluation, literature positioning, and constructive feedback generation. Trigger on queries involving paper URLs, uploaded PDFs, arXiv links, or requests like "review this paper", "analyze this research", "summarize this study", or "write a peer review".
+---
+
+# Academic Paper Review Skill
+
+## Overview
+
+This skill produces structured, peer-review-quality analyses of academic papers and research publications. It follows established academic review standards used by top-tier venues (NeurIPS, ICML, ACL, Nature, IEEE) to provide rigorous, constructive, and balanced assessments.
+
+The review covers **summary, strengths, weaknesses, methodology assessment, contribution evaluation, literature positioning, and actionable recommendations** — all grounded in evidence from the paper itself.
+
+## Core Capabilities
+
+- Parse and comprehend academic papers from uploaded PDFs or fetched URLs
+- Generate structured reviews following top-venue review templates
+- Assess methodology rigor (experimental design, statistical validity, reproducibility)
+- Evaluate novelty and significance of contributions
+- Position the work within the broader research landscape via targeted literature search
+- Identify limitations, gaps, and potential improvements
+- Produce both detailed review and concise executive summary formats
+- Support papers in any scientific domain (CS, biology, physics, social sciences, etc.)
+
+## When to Use This Skill
+
+**Always load this skill when:**
+
+- User provides a paper URL (arXiv, DOI, conference proceedings, journal link)
+- User uploads a PDF of a research paper or preprint
+- User asks to "review", "analyze", "critique", "assess", or "summarize" a research paper
+- User wants to understand the strengths and weaknesses of a study
+- User requests a peer-review-style evaluation of academic work
+- User asks for help preparing a review for a conference or journal submission
+
+## Review Methodology
+
+### Phase 1: Paper Comprehension
+
+Thoroughly read and understand the paper before forming any judgments.
+
+#### Step 1.1: Identify Paper Metadata
+
+Extract and record:
+
+| Field | Description |
+|-------|-------------|
+| **Title** | Full paper title |
+| **Authors** | Author list and affiliations |
+| **Venue / Status** | Publication venue, preprint server, or submission status |
+| **Year** | Publication or submission year |
+| **Domain** | Research field and subfield |
+| **Paper Type** | Empirical, theoretical, survey, position paper, systems paper, etc. |
+
+#### Step 1.2: Deep Reading Pass
+
+Read the paper systematically:
+
+1. **Abstract & Introduction** — Identify the claimed contributions and motivation
+2. **Related Work** — Note how authors position their work relative to prior art
+3. **Methodology** — Understand the proposed approach, model, or framework in detail
+4. **Experiments / Results** — Examine datasets, baselines, metrics, and reported outcomes
+5. **Discussion & Limitations** — Note any self-identified limitations
+6. **Conclusion** — Compare concluded claims against actual evidence presented
+
+#### Step 1.3: Key Claims Extraction
+
+List the paper's main claims explicitly:
+
+```
+Claim 1: [Specific claim about contribution or finding]
+Evidence: [What evidence supports this claim in the paper]
+Strength: [Strong / Moderate / Weak]
+
+Claim 2: [...]
+...
+```
+
+### Phase 2: Critical Analysis
+
+#### Step 2.1: Literature Context Search
+
+Use web search to understand the research landscape:
+
+```
+Search queries:
+- "[paper topic] state of the art [current year]"
+- "[key method name] comparison benchmark"
+- "[authors] previous work [topic]"
+- "[specific technique] limitations criticism"
+- "survey [research area] recent advances"
+```
+
+Use `web_fetch` on key related papers or surveys to understand where this work fits.
+
+#### Step 2.2: Methodology Assessment
+
+Evaluate the methodology using the following framework:
+
+| Criterion | Questions to Ask | Rating |
+|-----------|-----------------|--------|
+| **Soundness** | Is the approach technically correct? Are there logical flaws? | 1-5 |
+| **Novelty** | What is genuinely new vs. incremental improvement? | 1-5 |
+| **Reproducibility** | Are details sufficient to reproduce? Code/data available? | 1-5 |
+| **Experimental Design** | Are baselines fair? Are ablations adequate? Are datasets appropriate? | 1-5 |
+| **Statistical Rigor** | Are results statistically significant? Error bars reported? Multiple runs? | 1-5 |
+| **Scalability** | Does the approach scale? Are computational costs discussed? | 1-5 |
+
+#### Step 2.3: Contribution Significance Assessment
+
+Evaluate the significance level:
+
+| Level | Description | Criteria |
+|-------|-------------|----------|
+| **Landmark** | Fundamentally changes the field | New paradigm, widely applicable breakthrough |
+| **Significant** | Strong contribution advancing the state of the art | Clear improvement with solid evidence |
+| **Moderate** | Useful contribution with some limitations | Incremental but valid improvement |
+| **Marginal** | Minimal advance over existing work | Small gains, narrow applicability |
+| **Below threshold** | Does not meet publication standards | Fundamental flaws, insufficient evidence |
+
+#### Step 2.4: Strengths and Weaknesses Analysis
+
+For each strength or weakness, provide:
+- **What**: Specific observation
+- **Where**: Section/figure/table reference
+- **Why it matters**: Impact on the paper's claims or utility
+
+### Phase 3: Review Synthesis
+
+#### Step 3.1: Assemble the Structured Review
+
+Produce the final review using the template below.
+
+## Review Output Template
+
+```markdown
+# Paper Review: [Paper Title]
+
+## Paper Metadata
+- **Authors**: [Author list]
+- **Venue**: [Publication venue or preprint server]
+- **Year**: [Year]
+- **Domain**: [Research field]
+- **Paper Type**: [Empirical / Theoretical / Survey / Systems / Position]
+
+## Executive Summary
+
+[2-3 paragraph summary of the paper's core contribution, approach, and main findings.
+State your overall assessment upfront: what the paper does well, where it falls short,
+and whether the contribution is sufficient for the claimed venue/impact level.]
+
+## Summary of Contributions
+
+1. [First claimed contribution — one sentence]
+2. [Second claimed contribution — one sentence]
+3. [Additional contributions if any]
+
+## Strengths
+
+### S1: [Concise strength title]
+[Detailed explanation with specific references to sections, figures, or tables in the paper.
+Explain WHY this is a strength and its significance.]
+
+### S2: [Concise strength title]
+[...]
+
+### S3: [Concise strength title]
+[...]
+
+## Weaknesses
+
+### W1: [Concise weakness title]
+[Detailed explanation with specific references. Explain the impact of this weakness on
+the paper's claims. Suggest how it could be addressed.]
+
+### W2: [Concise weakness title]
+[...]
+
+### W3: [Concise weakness title]
+[...]
+
+## Methodology Assessment
+
+| Criterion | Rating (1-5) | Assessment |
+|-----------|:---:|------------|
+| Soundness | X | [Brief justification] |
+| Novelty | X | [Brief justification] |
+| Reproducibility | X | [Brief justification] |
+| Experimental Design | X | [Brief justification] |
+| Statistical Rigor | X | [Brief justification] |
+| Scalability | X | [Brief justification] |
+
+## Questions for the Authors
+
+1. [Specific question that would clarify a concern or ambiguity]
+2. [Question about methodology choices or alternative approaches]
+3. [Question about generalizability or practical applicability]
+
+## Minor Issues
+
+- [Typos, formatting issues, unclear figures, notation inconsistencies]
+- [Missing references that should be cited]
+- [Suggestions for improved clarity]
+
+## Literature Positioning
+
+[How does this work relate to the current state of the art?
+Are key related works cited? Are comparisons fair and comprehensive?
+What important related work is missing?]
+
+## Recommendations
+
+**Overall Assessment**: [Accept / Weak Accept / Borderline / Weak Reject / Reject]
+
+**Confidence**: [High / Medium / Low] — [Justification for confidence level]
+
+**Contribution Level**: [Landmark / Significant / Moderate / Marginal / Below threshold]
+
+### Actionable Suggestions for Improvement
+1. [Specific, constructive suggestion]
+2. [Specific, constructive suggestion]
+3. [Specific, constructive suggestion]
+```
+
+## Review Principles
+
+### Constructive Criticism
+- **Always suggest how to fix it** — Don't just point out problems; propose solutions
+- **Give credit where due** — Acknowledge genuine contributions even in flawed papers
+- **Be specific** — Reference exact sections, equations, figures, and tables
+- **Separate minor from major** — Distinguish fatal flaws from fixable issues
+
+### Objectivity Standards
+- ❌ "This paper is poorly written" (vague, unhelpful)
+- ✅ "Section 3.2 introduces notation X without formal definition, making the proof in Theorem 1 difficult to follow. Consider adding a notation table after the problem formulation." (specific, actionable)
+
+### Ethical Review Practices
+- Do NOT dismiss work based on author reputation or affiliation
+- Evaluate the work on its own merits
+- Flag potential ethical concerns (bias in datasets, dual-use implications) constructively
+- Maintain confidentiality of unpublished work
+
+## Adaptation by Paper Type
+
+| Paper Type | Focus Areas |
+|------------|-------------|
+| **Empirical** | Experimental design, baselines, statistical significance, ablations, reproducibility |
+| **Theoretical** | Proof correctness, assumption reasonableness, tightness of bounds, connection to practice |
+| **Survey** | Comprehensiveness, taxonomy quality, coverage of recent work, synthesis insights |
+| **Systems** | Architecture decisions, scalability evidence, real-world deployment, engineering contributions |
+| **Position** | Argument coherence, evidence for claims, impact potential, fairness of characterizations |
+
+## Common Pitfalls to Avoid
+
+- ❌ Reviewing the paper you wish was written instead of the paper that was submitted
+- ❌ Demanding additional experiments that are unreasonable in scope
+- ❌ Penalizing the paper for not solving a different problem
+- ❌ Being overly influenced by writing quality versus technical contribution
+- ❌ Treating absence of comparison to your own work as a weakness
+- ❌ Providing only a summary without critical analysis
+
+## Quality Checklist
+
+Before finalizing the review, verify:
+
+- [ ] Paper was read completely (not just abstract and introduction)
+- [ ] All major claims are identified and evaluated against evidence
+- [ ] At least 3 strengths and 3 weaknesses are provided with specific references
+- [ ] The methodology assessment table is complete with ratings and justifications
+- [ ] Questions for authors target genuine ambiguities, not rhetorical critiques
+- [ ] Literature search was conducted to contextualize the contribution
+- [ ] Recommendations are actionable and constructive
+- [ ] The overall assessment is consistent with the identified strengths and weaknesses
+- [ ] The review tone is professional and respectful
+- [ ] Minor issues are separated from major concerns
+
+## Output Format
+
+- Output the complete review in **Markdown** format
+- Save the review to `/mnt/user-data/outputs/review-{paper-topic}.md` when working in sandbox
+- Present the review to the user using the `present_files` tool
+
+## Notes
+
+- This skill complements the `deep-research` skill — load both when the user wants the paper reviewed in the context of the broader field
+- For papers behind paywalls, work with whatever content is accessible (abstract, publicly available versions, preprint mirrors)
+- Adapt the review depth to the user's needs: a brief assessment for quick triage versus a full review for submission preparation
+- When reviewing multiple papers comparatively, maintain consistent criteria across all reviews
+- Always disclose limitations of your review (e.g., "I could not verify the proofs in Appendix B in detail")
diff --git a/skills/public/code-documentation/SKILL.md b/skills/public/code-documentation/SKILL.md
new file mode 100644
index 000000000..8a2e2c47b
--- /dev/null
+++ b/skills/public/code-documentation/SKILL.md
@@ -0,0 +1,415 @@
+---
+name: code-documentation
+description: Use this skill when the user requests to generate, create, or improve documentation for code, APIs, libraries, repositories, or software projects. Supports README generation, API reference documentation, inline code comments, architecture documentation, changelog generation, and developer guides. Trigger on requests like "document this code", "create a README", "generate API docs", "write developer guide", or when analyzing codebases for documentation purposes.
+---
+
+# Code Documentation Skill
+
+## Overview
+
+This skill generates professional, comprehensive documentation for software projects, codebases, libraries, and APIs. It follows industry best practices from projects like React, Django, Stripe, and Kubernetes to produce documentation that is accurate, well-structured, and useful for both new contributors and experienced developers.
+
+The output ranges from single-file READMEs to multi-document developer guides, always matched to the project's complexity and the user's needs.
+
+## Core Capabilities
+
+- Generate comprehensive README.md files with badges, installation, usage, and API reference
+- Create API reference documentation from source code analysis
+- Produce architecture and design documentation with diagrams
+- Write developer onboarding and contribution guides
+- Generate changelogs from commit history or release notes
+- Create inline code documentation following language-specific conventions
+- Support JSDoc, docstrings, GoDoc, Javadoc, and Rustdoc formats
+- Adapt documentation style to the project's language and ecosystem
+
+## When to Use This Skill
+
+**Always load this skill when:**
+
+- User asks to "document", "create docs", or "write documentation" for any code
+- User requests a README, API reference, or developer guide
+- User shares a codebase or repository and wants documentation generated
+- User asks to improve or update existing documentation
+- User needs architecture documentation, including diagrams
+- User requests a changelog or migration guide
+
+## Documentation Workflow
+
+### Phase 1: Codebase Analysis
+
+Before writing any documentation, thoroughly understand the codebase.
+
+#### Step 1.1: Project Discovery
+
+Identify the project fundamentals:
+
+| Field | How to Determine |
+|-------|-----------------|
+| **Language(s)** | Check file extensions, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc. |
+| **Framework** | Look at dependencies for known frameworks (React, Django, Express, Spring, etc.) |
+| **Build System** | Check for `Makefile`, `CMakeLists.txt`, `webpack.config.js`, `build.gradle`, etc. |
+| **Package Manager** | npm/yarn/pnpm, pip/uv/poetry, cargo, go modules, etc. |
+| **Project Structure** | Map out the directory tree to understand the architecture |
+| **Entry Points** | Find main files, CLI entry points, exported modules |
+| **Existing Docs** | Check for existing README, docs/, wiki, or inline documentation |
+
+#### Step 1.2: Code Structure Analysis
+
+Use sandbox tools to explore the codebase:
+
+```bash
+# Get directory structure
+ls /mnt/user-data/uploads/project-dir/
+
+# Read key files
+read_file /mnt/user-data/uploads/project-dir/package.json
+read_file /mnt/user-data/uploads/project-dir/pyproject.toml
+
+# Search for public API surfaces
+grep -r "export " /mnt/user-data/uploads/project-dir/src/
+grep -r "def " /mnt/user-data/uploads/project-dir/src/ --include="*.py"
+grep -r "func " /mnt/user-data/uploads/project-dir/ --include="*.go"
+```
+
+#### Step 1.3: Identify Documentation Scope
+
+Based on analysis, determine what documentation to produce:
+
+| Project Size | Recommended Documentation |
+|-------------|--------------------------|
+| **Single file / script** | Inline comments + usage header |
+| **Small library** | README with API reference |
+| **Medium project** | README + API docs + examples |
+| **Large project** | README + Architecture + API + Contributing + Changelog |
+
+### Phase 2: Documentation Generation
+
+#### Step 2.1: README Generation
+
+Every project needs a README. Follow this structure:
+
+```markdown
+# Project Name
+
+[One-line project description — what it does and why it matters]
+
+[![Badge](link)](#) [![Badge](link)](#)
+
+## Features
+
+- [Key feature 1 — brief description]
+- [Key feature 2 — brief description]
+- [Key feature 3 — brief description]
+
+## Quick Start
+
+### Prerequisites
+
+- [Prerequisite 1 with version requirement]
+- [Prerequisite 2 with version requirement]
+
+### Installation
+
+[Installation commands with copy-paste-ready code blocks]
+
+### Basic Usage
+
+[Minimal working example that demonstrates core functionality]
+
+## Documentation
+
+- [Link to full API reference if separate]
+- [Link to architecture docs if separate]
+- [Link to examples directory if applicable]
+
+## API Reference
+
+[Inline API reference for smaller projects OR link to generated docs]
+
+## Configuration
+
+[Environment variables, config files, or runtime options]
+
+## Examples
+
+[2-3 practical examples covering common use cases]
+
+## Development
+
+### Setup
+
+[How to set up a development environment]
+
+### Testing
+
+[How to run tests]
+
+### Building
+
+[How to build the project]
+
+## Contributing
+
+[Contribution guidelines or link to CONTRIBUTING.md]
+
+## License
+
+[License information]
+```
+
+#### Step 2.2: API Reference Generation
+
+For each public API surface, document:
+
+**Function / Method Documentation**:
+
+```markdown
+### `functionName(param1, param2, options?)`
+
+Brief description of what this function does.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `param1` | `string` | Yes | — | Description of param1 |
+| `param2` | `number` | Yes | — | Description of param2 |
+| `options` | `Object` | No | `{}` | Configuration options |
+| `options.timeout` | `number` | No | `5000` | Timeout in milliseconds |
+
+**Returns:** `Promise<Result>` — Description of return value
+
+**Throws:**
+- `ValidationError` — When param1 is empty
+- `TimeoutError` — When the operation exceeds the timeout
+
+**Example:**
+
+\`\`\`javascript
+const result = await functionName("hello", 42, { timeout: 10000 });
+console.log(result.data);
+\`\`\`
+```
+
+**Class Documentation**:
+
+```markdown
+### `ClassName`
+
+Brief description of the class and its purpose.
+
+**Constructor:**
+
+\`\`\`javascript
+new ClassName(config)
+\`\`\`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config.option1` | `string` | Description |
+| `config.option2` | `boolean` | Description |
+
+**Methods:**
+
+- [`method1()`](#method1) — Brief description
+- [`method2(param)`](#method2) — Brief description
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `property1` | `string` | Description |
+| `property2` | `number` | Read-only. Description |
+```
+
+#### Step 2.3: Architecture Documentation
+
+For medium-to-large projects, include architecture documentation:
+
+```markdown
+# Architecture Overview
+
+## System Diagram
+
+[Include a Mermaid diagram showing the high-level architecture]
+
+\`\`\`mermaid
+graph TD
+    A[Client] --> B[API Gateway]
+    B --> C[Service A]
+    B --> D[Service B]
+    C --> E[(Database)]
+    D --> E
+\`\`\`
+
+## Component Overview
+
+### Component Name
+- **Purpose**: What this component does
+- **Location**: `src/components/name/`
+- **Dependencies**: What it depends on
+- **Public API**: Key exports or interfaces
+
+## Data Flow
+
+[Describe how data flows through the system for key operations]
+
+## Design Decisions
+
+### Decision Title
+- **Context**: What situation led to this decision
+- **Decision**: What was decided
+- **Rationale**: Why this approach was chosen
+- **Trade-offs**: What was sacrificed
+```
+
+#### Step 2.4: Inline Code Documentation
+
+Generate language-appropriate inline documentation:
+
+**Python (Docstrings — Google style)**:
+```python
+def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
+    """Process data from the given file path.
+
+    Reads the input file, applies transformations based on the provided
+    options, and returns a structured result object.
+
+    Args:
+        input_path: Absolute path to the input data file.
+            Supports CSV, JSON, and Parquet formats.
+        options: Optional configuration dictionary.
+            - "validate" (bool): Enable input validation. Defaults to True.
+            - "format" (str): Output format ("json" or "csv"). Defaults to "json".
+
+    Returns:
+        A ProcessResult containing the transformed data and metadata.
+
+    Raises:
+        FileNotFoundError: If input_path does not exist.
+        ValidationError: If validation is enabled and data is malformed.
+
+    Example:
+        >>> result = process_data("/data/input.csv", {"validate": True})
+        >>> print(result.row_count)
+        1500
+    """
+```
+
+**TypeScript (JSDoc / TSDoc)**:
+```typescript
+/**
+ * Fetches user data from the API and transforms it for display.
+ *
+ * @param userId - The unique identifier of the user
+ * @param options - Configuration options for the fetch operation
+ * @param options.includeProfile - Whether to include the full profile. Defaults to `false`.
+ * @param options.cache - Cache duration in seconds. Set to `0` to disable.
+ * @returns The transformed user data ready for rendering
+ * @throws {NotFoundError} When the user ID does not exist
+ * @throws {NetworkError} When the API is unreachable
+ *
+ * @example
+ * ```ts
+ * const user = await fetchUser("usr_123", { includeProfile: true });
+ * console.log(user.displayName);
+ * ```
+ */
+```
+
+**Go (GoDoc)**:
+```go
+// ProcessData reads the input file at the given path, applies the specified
+// transformations, and returns the processed result.
+//
+// The input path must be an absolute path to a CSV or JSON file.
+// If options is nil, default options are used.
+//
+// ProcessData returns an error if the file does not exist or cannot be parsed.
+func ProcessData(inputPath string, options *ProcessOptions) (*Result, error) {
+```
+
+### Phase 3: Quality Assurance
+
+#### Step 3.1: Documentation Completeness Check
+
+Verify the documentation covers:
+
+- [ ] **What it is** — Clear project description that a newcomer can understand
+- [ ] **Why it exists** — Problem it solves and value proposition
+- [ ] **How to install** — Copy-paste-ready installation commands
+- [ ] **How to use** — At least one minimal working example
+- [ ] **API surface** — All public functions, classes, and types documented
+- [ ] **Configuration** — All environment variables, config files, and options
+- [ ] **Error handling** — Common errors and how to resolve them
+- [ ] **Contributing** — How to set up dev environment and submit changes
+
+#### Step 3.2: Quality Standards
+
+| Standard | Check |
+|----------|-------|
+| **Accuracy** | Every code example must actually work with the described API |
+| **Completeness** | No public API surface left undocumented |
+| **Consistency** | Same formatting and structure throughout |
+| **Freshness** | Documentation matches the current code, not an older version |
+| **Accessibility** | No jargon without explanation, acronyms defined on first use |
+| **Examples** | Every complex concept has at least one practical example |
+
+#### Step 3.3: Cross-reference Validation
+
+Ensure:
+- All mentioned file paths exist in the project
+- All referenced functions and classes exist in the code
+- All code examples use the correct function signatures
+- Version numbers match the project's actual version
+- All links (internal and external) are valid
+
+## Documentation Style Guide
+
+### Writing Principles
+
+1. **Lead with the "why"** — Before explaining how something works, explain why it exists
+2. **Progressive disclosure** — Start simple, add complexity gradually
+3. **Show, don't tell** — Prefer code examples over lengthy explanations
+4. **Active voice** — "The function returns X" not "X is returned by the function"
+5. **Present tense** — "The server starts on port 8080" not "The server will start on port 8080"
+6. **Second person** — "You can configure..." not "Users can configure..."
+
+### Formatting Rules
+
+- Use ATX-style headers (`#`, `##`, `###`)
+- Use fenced code blocks with language specification (` ```python `, ` ```bash `)
+- Use tables for structured information (parameters, options, configuration)
+- Use admonitions for important notes, warnings, and tips
+- Keep line length readable (wrap prose at ~80-100 characters in source)
+- Use `code formatting` for function names, file paths, variable names, and CLI commands
+
+### Language-Specific Conventions
+
+| Language | Doc Format | Style Guide |
+|----------|-----------|-------------|
+| Python | Google-style docstrings | PEP 257 |
+| TypeScript/JavaScript | TSDoc / JSDoc | TypeDoc conventions |
+| Go | GoDoc comments | Effective Go |
+| Rust | Rustdoc (`///`) | Rust API Guidelines |
+| Java | Javadoc | Oracle Javadoc Guide |
+| C/C++ | Doxygen | Doxygen manual |
+
+## Output Handling
+
+After generation:
+
+- Save documentation files to `/mnt/user-data/outputs/`
+- For multi-file documentation, maintain the project directory structure
+- Present generated files to the user using the `present_files` tool
+- Offer to iterate on specific sections or adjust the level of detail
+- Suggest additional documentation that might be valuable
+
+## Notes
+
+- Always analyze the actual code before writing documentation — never guess at API signatures or behavior
+- When existing documentation exists, preserve its structure unless the user explicitly asks for a rewrite
+- For large codebases, prioritize documenting the public API surface and key abstractions first
+- Documentation should be written in the same language as the project's existing docs; default to English if none exist
+- When generating changelogs, use the [Keep a Changelog](https://keepachangelog.com/) format
+- This skill works well in combination with the `deep-research` skill for documenting third-party integrations or dependencies
diff --git a/skills/public/newsletter-generation/SKILL.md b/skills/public/newsletter-generation/SKILL.md
new file mode 100644
index 000000000..0f0221e50
--- /dev/null
+++ b/skills/public/newsletter-generation/SKILL.md
@@ -0,0 +1,343 @@
+---
+name: newsletter-generation
+description: Use this skill when the user requests to generate, create, write, or draft a newsletter, email digest, weekly roundup, industry briefing, or curated content summary. Supports topic-based research, content curation from multiple sources, and professional formatting for email or web distribution. Trigger on requests like "create a newsletter about X", "write a weekly digest", "generate a tech roundup", or "curate news about Y".
+---
+
+# Newsletter Generation Skill
+
+## Overview
+
+This skill generates professional, well-researched newsletters that combine curated content from multiple sources with original analysis and commentary. It follows modern newsletter best practices from publications like Morning Brew, The Hustle, TLDR, and Benedict Evans to produce content that is informative, engaging, and actionable.
+
+The output is a complete, ready-to-publish newsletter in Markdown format, suitable for email distribution platforms, web publishing, or conversion to HTML.
+
+## Core Capabilities
+
+- Research and curate content from multiple web sources on specified topics
+- Generate topic-focused or multi-topic newsletters with consistent voice
+- Write engaging headlines, summaries, and original commentary
+- Structure content for optimal readability and scanning
+- Support multiple newsletter formats (daily digest, weekly roundup, deep-dive, industry briefing)
+- Include relevant links, sources, and attributions
+- Adapt tone and style to target audience (technical, executive, general)
+- Generate recurring newsletter series with consistent branding and structure
+
+## When to Use This Skill
+
+**Always load this skill when:**
+
+- User asks to generate a newsletter, email digest, or content roundup
+- User requests a curated summary of news or developments on a topic
+- User wants to create a recurring newsletter format
+- User asks to compile recent developments in a field into a briefing
+- User needs a formatted email-ready content piece with multiple curated items
+- User asks for a "weekly roundup", "monthly digest", or "morning briefing"
+
+## Newsletter Workflow
+
+### Phase 1: Planning
+
+#### Step 1.1: Understand Newsletter Requirements
+
+Identify the key parameters:
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| **Topic(s)** | Primary subject area(s) to cover | Required |
+| **Format** | Daily digest, weekly roundup, deep-dive, or industry briefing | Weekly roundup |
+| **Target Audience** | Technical, executive, general, or niche community | General |
+| **Tone** | Professional, conversational, witty, or analytical | Conversational-professional |
+| **Length** | Short (5-min read), medium (10-min), long (15-min+) | Medium |
+| **Sections** | Number and type of content sections | 4-6 sections |
+| **Frequency Context** | One-time or part of a recurring series | One-time |
+
+#### Step 1.2: Define Newsletter Structure
+
+Based on the format, select the appropriate structure:
+
+**Daily Digest Structure**:
+```
+1. Top Story (1 item, detailed)
+2. Quick Hits (3-5 items, brief)
+3. One Stat / Quote of the Day
+4. What to Watch
+```
+
+**Weekly Roundup Structure**:
+```
+1. Editor's Note / Intro
+2. Top Stories (2-3 items, detailed)
+3. Trends & Analysis (1-2 items, original commentary)
+4. Quick Bites (4-6 items, brief summaries)
+5. Tools & Resources (2-3 items)
+6. One More Thing / Closing
+```
+
+**Deep-Dive Structure**:
+```
+1. Introduction & Context
+2. Background / Why It Matters
+3. Key Developments (detailed analysis)
+4. Expert Perspectives
+5. What's Next / Implications
+6. Further Reading
+```
+
+**Industry Briefing Structure**:
+```
+1. Executive Summary
+2. Market Developments
+3. Company News & Moves
+4. Product & Technology Updates
+5. Regulatory & Policy Changes
+6. Data & Metrics
+7. Outlook
+```
+
+### Phase 2: Research & Curation
+
+#### Step 2.1: Multi-Source Research
+
+Conduct thorough research using web search. **The quality of the newsletter depends directly on the quality and recency of research.**
+
+**Search Strategy**:
+
+```
+# Current news and developments
+"[topic] news [current month] [current year]"
+"[topic] latest developments"
+"[topic] announcement this week"
+
+# Trends and analysis
+"[topic] trends [current year]"
+"[topic] analysis expert opinion"
+"[topic] industry report"
+
+# Data and statistics
+"[topic] statistics [current year]"
+"[topic] market data latest"
+"[topic] growth metrics"
+
+# Tools and resources
+"[topic] new tools [current year]"
+"[topic] open source release"
+"best [topic] resources [current year]"
+```
+
+> **IMPORTANT**: Always check `<current_date>` to ensure search queries use the correct temporal context. Never use hardcoded years.
+
+#### Step 2.2: Source Evaluation and Selection
+
+Evaluate each source and curate the best content:
+
+| Criterion | Priority |
+|-----------|----------|
+| **Recency** | Prefer content from the last 7-30 days |
+| **Authority** | Prioritize primary sources, official announcements, established publications |
+| **Uniqueness** | Select stories that offer fresh perspective or are underreported |
+| **Relevance** | Every item must clearly connect to the newsletter's stated topic(s) |
+| **Actionability** | Prefer content readers can act on (tools, insights, strategies) |
+| **Diversity** | Mix of news, analysis, data, and practical resources |
+
+#### Step 2.3: Deep Content Extraction
+
+For key stories, use `web_fetch` to read full articles and extract:
+
+1. **Core facts** — What happened, who is involved, when
+2. **Context** — Why this matters, background information
+3. **Data points** — Specific numbers, metrics, or statistics
+4. **Quotes** — Relevant expert quotes or official statements
+5. **Implications** — What this means for the reader
+
+### Phase 3: Writing
+
+#### Step 3.1: Newsletter Header
+
+Every newsletter starts with a consistent header:
+
+```markdown
+# [Newsletter Name]
+
+*[Tagline or description] — [Date]*
+
+---
+
+[Optional: One-sentence preview of what's inside]
+```
+
+#### Step 3.2: Section Writing Guidelines
+
+**Top Stories / Featured Items**:
+- **Headline**: Compelling, clear, benefit-oriented (not clickbait)
+- **Hook**: Opening sentence that makes the reader care (1-2 sentences)
+- **Body**: Key facts and context (2-4 paragraphs)
+- **Why it matters**: Connect to the reader's world (1 paragraph)
+- **Source link**: Always attribute and link to the original source
+
+**Quick Bites / Brief Items**:
+- **Format**: Bold headline + 2-3 sentence summary + source link
+- **Focus**: One key takeaway per item
+- **Efficiency**: Readers should get the essential insight without clicking through
+
+**Analysis / Commentary Sections**:
+- **Voice**: The newsletter's unique perspective on trends or developments
+- **Structure**: Observation → Context → Implication → (Optional) Actionable takeaway
+- **Evidence**: Every claim backed by data or sourced information
+
+#### Step 3.3: Writing Standards
+
+| Principle | Implementation |
+|-----------|---------------|
+| **Scannable** | Use headers, bold text, bullet points, and short paragraphs |
+| **Engaging** | Lead with the most interesting angle, not chronological order |
+| **Concise** | Every sentence earns its place — cut filler ruthlessly |
+| **Accurate** | Every fact is sourced, every number is verified |
+| **Attributive** | Always credit original sources with inline links |
+| **Human** | Write like a knowledgeable friend, not a press release |
+
+**Tone Calibration by Audience**:
+
+| Audience | Tone | Example |
+|----------|------|---------|
+| **Technical** | Precise, no jargon explanations, assumed expertise | "The new API supports gRPC streaming with backpressure handling via flow control windows." |
+| **Executive** | Impact-focused, bottom-line, strategic | "This acquisition gives Company X a 40% market share in the enterprise segment, directly threatening Incumbent Y's pricing power." |
+| **General** | Accessible, analogies, explains concepts | "Think of it like a universal translator for data — it lets any app talk to any database without learning a new language." |
+
+### Phase 4: Assembly & Polish
+
+#### Step 4.1: Assemble the Newsletter
+
+Combine all sections into the final document following the chosen structure template.
+
+#### Step 4.2: Footer
+
+Every newsletter ends with:
+
+```markdown
+---
+
+*[Newsletter Name] is [description of what it is].*
+*[How to subscribe/share/give feedback]*
+
+*Sources: All links are provided inline. This newsletter curates and summarizes
+publicly available information with original commentary.*
+```
+
+#### Step 4.3: Quality Checklist
+
+Before finalizing, verify:
+
+- [ ] **Every factual claim has a source link** — No unsourced assertions
+- [ ] **All links are functional** — Verified URLs from search results
+- [ ] **Date references use the actual current date** — No hardcoded or assumed dates
+- [ ] **Content is current** — All major items are from within the expected timeframe
+- [ ] **No duplicate stories** — Each item appears only once
+- [ ] **Consistent formatting** — Headers, bullets, links use the same style throughout
+- [ ] **Balanced coverage** — Not dominated by a single source or perspective
+- [ ] **Appropriate length** — Matches the specified length target
+- [ ] **Engaging opening** — The first 2 sentences make the reader want to continue
+- [ ] **Clear closing** — The newsletter ends with a memorable or actionable note
+- [ ] **Proofread** — No typos, broken formatting, or incomplete sentences
+
+## Newsletter Output Template
+
+```markdown
+# [Newsletter Name]
+
+*[Tagline] — [Full date, e.g., April 4, 2026]*
+
+---
+
+[Preview sentence: "This week: [topic 1], [topic 2], and [topic 3]."]
+
+## 🔥 Top Stories
+
+### [Headline 1]
+
+[Hook — why this matters in 1-2 sentences.]
+
+[Body — 2-4 paragraphs covering key facts, context, and implications.]
+
+**Why it matters:** [1 paragraph connecting to reader's interests or industry impact.]
+
+📎 [Source: Publication Name](URL)
+
+### [Headline 2]
+
+[Same structure as above]
+
+## 📊 Trends & Analysis
+
+### [Trend Title]
+
+[Original commentary on an emerging trend, backed by data from research.]
+
+[Key data points presented clearly — consider inline stats or a brief comparison.]
+
+**The bottom line:** [One-sentence takeaway.]
+
+## ⚡ Quick Bites
+
+- **[Headline]** — [2-3 sentence summary with key takeaway.] [Source](URL)
+- **[Headline]** — [2-3 sentence summary.] [Source](URL)
+- **[Headline]** — [2-3 sentence summary.] [Source](URL)
+- **[Headline]** — [2-3 sentence summary.] [Source](URL)
+
+## 🛠️ Tools & Resources
+
+- **[Tool/Resource Name]** — [What it does and why it's useful.] [Link](URL)
+- **[Tool/Resource Name]** — [Description.] [Link](URL)
+
+## 💬 One More Thing
+
+[Closing thought, insightful quote, or forward-looking statement.]
+
+---
+
+*[Newsletter Name] curates the most important [topic] news and analysis.*
+*Found this useful? Share it with a colleague.*
+
+*All sources are linked inline. Views and commentary are original.*
+```
+
+## Adaptation Examples
+
+### Technology Newsletter
+- Emoji usage: ✅ Moderate (section headers)
+- Sections: Top Stories, Deep Dive, Quick Bites, Open Source Spotlight, Dev Tools
+- Tone: Technical-conversational
+
+### Business/Finance Newsletter
+- Emoji usage: ❌ Minimal to none
+- Sections: Market Overview, Deal Flow, Company News, Data Corner, Outlook
+- Tone: Professional-analytical
+
+### Industry-Specific Newsletter
+- Emoji usage: Moderate
+- Sections: Regulatory Updates, Market Data, Innovation Watch, People Moves, Events
+- Tone: Expert-authoritative
+
+### Creative/Marketing Newsletter
+- Emoji usage: ✅ Liberal
+- Sections: Campaign Spotlight, Trend Watch, Viral This Week, Tools We Love, Inspiration
+- Tone: Enthusiastic-professional
+
+## Output Handling
+
+After generation:
+
+- Save the newsletter to `/mnt/user-data/outputs/newsletter-{topic}-{date}.md`
+- Present the newsletter to the user using the `present_files` tool
+- Offer to adjust sections, tone, length, or focus areas
+- If the user wants HTML output, note that the Markdown can be converted using standard tools
+
+## Notes
+
+- This skill works best in combination with the `deep-research` skill for comprehensive topic coverage — load both for newsletters requiring deep analysis
+- Always use `<current_date>` for temporal context in searches and date references in the newsletter
+- For recurring newsletters, suggest maintaining a consistent structure so readers develop expectations
+- When curating, quality beats quantity — 5 excellent items beat 15 mediocre ones
+- Attribute all content properly — newsletters build trust through transparent sourcing
+- Avoid summarizing paywalled content that the reader cannot access
+- If the user provides specific URLs or articles to include, incorporate them alongside your curated findings
+- The newsletter should provide enough value in the summaries that readers benefit even without clicking through to every link