galaxy-dawn/bug-detective

开发者: galaxy-dawn许可证: MIT6k

Use when creating or configuring Claude Code agents and their frontmatter.

关于Skill 介绍README常见问题

当用户要求“调试这个”、“修复这个错误”、“调查这个bug”、“排查这个问题”、“找到问题所在”、“某些东西坏了”、“这不起作用”、“为什么这会失败”，或者报告错误/异常/bug时，应该使用这项技能。提供系统化的调试流程和常见的错误模式。 --- 这项技能为学术写作中的引用验证提供了参考指南。当用户询问“引用验证的最佳实践”、“如何验证参考文献”、“防止虚假引用”，或需要关于引用准确性的指导时使用。该技能通过提供详细的验证原则和常见错误模式来支持机器学习论文写作。 --- 当用户要求“生成日报”、“在arXiv上搜索EEG论文”、“查找EEG解码论文”、“回顾脑机接口论文”，或者想要为EEG/脑解码/语音解码研究创建论文摘要时使用。此技能可自动在arXiv上搜索关于EEG解码、EEG语音解码或脑基础模型的最新论文，评估论文质量，并生成结构化的中英文摘要。 --- 每日编码助手，在编写/修改代码时自动触发，提供核心检查清单。✅ 触发场景：- 实现新功能、添加代码、修改现有代码 - 用户请求“写一个...”，“实现...”，“添加...”，“修改...” - 任何涉及编辑/写作工具的编码任务 ❌ 不会触发：- 纯阅读/理解代码（无修改意图）- 已经由专门技能覆盖的情况（如找bug专家、架构设计、TDD指南）- 配置文件更改、文档撰写 --- 当用户要求“审查论文质量”、“检查论文完整性”、“验证论文结构”、“提交前自审”，或提到系统性论文质量检查时，应使用此技能。提供全面的学术论文质量保证检查清单。 --- 当用户要求“准备会议演讲”、“创建演示文稿幻灯片”、“设计海报”、“制作学术海报”、“撰写推广内容”、“创建Twitter帖子串”，或提到接受后的会议准备时，应使用此技能。提供全面的工作流程，用于创建演示文稿、海报和推广内容。 --- 当用户要求“分析技能质量”、“评估此技能”、“审查技能质量”、“检查我的技能”或“生成质量报告”时，应使用此技能。它会根据描述质量、内容组织、写作风格和结构完整性来评估本地技能。 --- 从评论分析到撰写专业反驳的系统性评审回复工作流程。当用户要求“撰写反驳”、“回应审稿人”、“起草评审回复”或“分析评审意见”时使用。提高论文接受率。 --- 当用户要求“分析实验结果”、“生成结果部分”、“实验的统计分析”、“比较模型性能”、“创建结果可视化”，或提到将实验数据与论文写作联系起来时，应使用此技能。为分析ML/AI实验结果并生成可用于论文的内容提供全面指导。 --- 当用户要求“头脑风暴研究想法”、“使用5W1H框架”、“识别研究空白”、“进行差距分析”、“开始研究项目”、“进行文献回顾”、“定义研究问题”、“选择研究方法”、“规划研究”，或提到研究项目的启动阶段时，应使用此技能。提供从创意生成到规划的研究启动工作流程的全面指导。 --- 当用户要求“去除AI写作模式”、“使文本更人性化”、“让这听起来更自然”、“删除AI生成的痕迹”、“修正机械式写作”，或者需要从散文中消除AI写作模式时，应使用此技能。支持英文和中文文本。基于维基百科的“AI写作迹象”指南，检测并修正夸张的象征、促销语言、表面的-ing分析、模糊的归属、AI词汇、负面平行结构以及过多的连词短语。 --- 当用户请求“创建插件”、“搭建插件框架”、“理解插件结构”、“组织插件组件”、“设置plugin.json”、“使用${CLAUDE_PLUGIN_ROOT}”、“添加命令/代理/技能/钩子”、“配置自动发现”，或需要关于插件目录布局、清单配置、组件组织、文件命名约定，或是Claude Code插件架构最佳实践的指导时，应使用此技能。

重要提示：本站仅作 Skill 资源导航与收录，正文以 GitHub 原仓库为准，版权归原项目所有。

文件

索引更新于 11/2/2026, 2:50:42 AM

skills/agent-identifier/SKILL.md10.4 KB当前在 GitHub 查看 ↗

skills/agent-identifier/references/agent-creation-system-prompt.md8.7 KB在 GitHub 查看 ↗

skills/agent-identifier/references/system-prompt-design.md9.8 KB在 GitHub 查看 ↗

skills/agent-identifier/references/triggering-examples.md11.3 KB在 GitHub 查看 ↗

Agent Development for Claude Code Plugins

Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.

Key concepts:

Agents are FOR autonomous work, commands are FOR user-initiated actions
Markdown file format with YAML frontmatter
Triggering via description field with examples
System prompt defines agent behavior
Model and color customization

When to Use

Use this skill when the user asks to:

Create an agent
Add an agent
Write a subagent
Define agent frontmatter
Decide when to use description examples
Configure agent tools, colors, or model behavior
Design autonomous agent structure, triggering conditions, or system prompts

When Not to Use

Do not use this skill for:

Slash command design
Hook configuration
MCP server setup
General plugin layout questions that belong to plugin-structure

Agent File Structure

Complete Format

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Frontmatter Fields

name (required)

Agent identifier used for namespacing and invocation.

Format: lowercase, numbers, hyphens only Length: 3-50 characters Pattern: Must start and end with alphanumeric

Good examples:

code-reviewer
test-generator
api-docs-writer
security-analyzer

Bad examples:

helper (too generic)
-agent- (starts/ends with hyphen)
my_agent (underscores not allowed)
ag (too short, < 3 chars)

description (required)

Defines when Claude should trigger this agent. This is the most critical field.

Must include:

Triggering conditions ("Use this agent when...")
Multiple <example> blocks showing usage
Context, user request, and assistant response in each example
<commentary> explaining why agent triggers

Format:

Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]

Best practices:

Include 2-4 concrete examples
Show proactive and reactive triggering
Cover different phrasings of same intent
Explain reasoning in commentary
Be specific about when NOT to use the agent

model (required)

Which model the agent should use.

Options:

inherit - Use same model as parent (recommended)
sonnet - Claude Sonnet (balanced)
opus - Claude Opus (most capable, expensive)
haiku - Claude Haiku (fast, cheap)

Recommendation: Use inherit unless agent needs specific model capabilities.

color (required)

Visual identifier for agent in UI.

Options: blue, cyan, green, yellow, magenta, red

Guidelines:

Choose distinct colors for different agents in same plugin
Use consistent colors for similar agent types
Blue/cyan: Analysis, review
Green: Success-oriented tasks
Yellow: Caution, validation
Red: Critical, security
Magenta: Creative, generation

tools (optional)

Restrict agent to specific tools.

Format: Array of tool names

tools: ["Read", "Write", "Grep", "Bash"]

Default: If omitted, agent has access to all tools

Best practice: Limit tools to minimum needed (principle of least privilege)

Common tool sets:

Read-only analysis: ["Read", "Grep", "Glob"]
Code generation: ["Read", "Write", "Grep"]
Testing: ["Read", "Bash", "Grep"]
Full access: Omit field or use ["*"]

System Prompt Design

The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.

Structure

Standard template:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

Best Practices

✅ DO:

Write in second person ("You are...", "You will...")
Be specific about responsibilities
Provide step-by-step process
Define output format
Include quality standards
Address edge cases
Keep under 10,000 characters

❌ DON'T:

Write in first person ("I am...", "I will...")
Be vague or generic
Omit process steps
Leave output format undefined
Skip quality guidance
Ignore error cases

Creating Agents

Method 1: AI-Assisted Generation

Use this prompt pattern (extracted from Claude Code):

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

Then convert to agent file format with frontmatter.

See examples/agent-creation-prompt.md for complete template.

Method 2: Manual Creation

Choose agent identifier (3-50 chars, lowercase, hyphens)
Write description with examples
Select model (usually inherit)
Choose color for visual identification
Define tools (if restricting access)
Write system prompt with structure above
Save as agents/agent-name.md

Validation Rules

Identifier Validation

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

Rules:

3-50 characters
Lowercase letters, numbers, hyphens only
Must start and end with alphanumeric
No underscores, spaces, or special characters

Description Validation

Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples

System Prompt Validation

Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format

Agent Organization

Plugin Agents Directory

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

All .md files in agents/ are auto-discovered.

Namespacing

Agents are namespaced automatically:

Single plugin: agent-name
With subdirectories: plugin:subdir:agent-name

Testing Agents

Test Triggering

Create test scenarios to verify agent triggers correctly:

Write agent with specific triggering examples
Use similar phrasing to examples in test
Check Claude loads the agent
Verify agent provides expected functionality

Test System Prompt

Ensure system prompt is complete:

Give agent typical task
Check it follows process steps
Verify output format is correct
Test edge cases mentioned in prompt
Confirm quality standards are met

Quick Reference

Minimal Agent

---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Frontmatter Fields Summary

Field	Required	Format	Example
name	Yes	lowercase-hyphens	code-reviewer
description	Yes	Text + examples	Use when... ...
model	Yes	inherit/sonnet/opus/haiku	inherit
color	Yes	Color name	blue
tools	No	Array of tool names	["Read", "Grep"]

Best Practices

DO:

✅ Include 2-4 concrete examples in description
✅ Write specific triggering conditions
✅ Use inherit for model unless specific need
✅ Choose appropriate tools (least privilege)
✅ Write clear, structured system prompts
✅ Test agent triggering thoroughly

DON'T:

❌ Use generic descriptions without examples
❌ Omit triggering conditions
❌ Give all agents same color
❌ Grant unnecessary tool access
❌ Write vague system prompts
❌ Skip testing

Additional Resources

Reference Files

For detailed guidance, consult:

references/system-prompt-design.md - Complete system prompt patterns
references/triggering-examples.md - Example formats and best practices
references/agent-creation-system-prompt.md - The exact prompt from Claude Code

Example Files

Working examples in examples/:

agent-creation-prompt.md - AI-assisted agent generation template
complete-agent-examples.md - Full agent examples for different use cases

Utility Scripts

Development tools in scripts/:

validate-agent.sh - Validate agent file structure
test-agent-trigger.sh - Test if agent triggers correctly

Implementation Workflow

To create an agent for a plugin:

Define agent purpose and triggering conditions
Choose creation method (AI-assisted or manual)
Create agents/agent-name.md file
Write frontmatter with all required fields
Write system prompt following best practices
Include 2-4 triggering examples in description
Validate with scripts/validate-agent.sh
Test triggering with real scenarios
Document agent in plugin README

Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.

重要提示：本站仅作 Skill 资源导航与收录，正文以 GitHub 原仓库为准，版权归原项目所有。

Last Commit

Language: English | 中文 | 日本語

Supported Platforms: Claude Code | Codex CLI | Kimi Code CLI | OpenCode

Semi-automated research assistant for academic research and software development, especially for computer science and AI researchers. Supports Claude Code, Codex CLI, Kimi Code CLI, and OpenCode across literature review, coding, experiments, reporting, writing, and project knowledge management.

Branch note: the main branch is the Claude Code workflow. If you use Codex CLI, please see the codex branch. If you use Kimi Code CLI, please see the kimi branch. If you use OpenCode, please see the opencode branch.

Recent News

2026-06-03: Kimi Code CLI branch added with strong support from Kimi — added the kimi branch as the Kimi Code CLI edition of Claude Scholar and thank the Kimi team for their strong support of this project.
2026-05-14: expression-skill made the communication core, planning-with-files restored as the default persistence layer, and the Nature writing stack expanded — made expression-skill the explicit conclusion-first discipline for reporting, planning, file operations, and multi-step technical work; reintroduced planning-with-files as the default on-disk planning and progress-tracking workflow for complex tasks; introduced nature-writing for section drafting and argument construction; refreshed nature-polishing to the latest upstream article-pattern release; and kept nature-response plus nature-data in the journal-writing stack.
2026-05-13: Evidence-gated research workflow and Sources/Papers routing tightened — added a shared research-contract.md for Evidence Records, claim strength, and Claim Promotion Gates; connected research ideation, Zotero ingestion, literature synthesis, results reporting, writing, and rebuttal workflows to that contract; and clarified that project paper notes live under Sources/Papers before promoted claims move into Knowledge or Writing.
2026-04-24: Project-scoped Obsidian KB workflow consolidated — rebuilt Obsidian project knowledge management into a vault-first workflow, consolidated the older overlapping memory skills into four focused skills, kept repo-local project binding metadata as a runtime layer, and made project navigation human-first instead of a machine registry dump.
2026-04-22: Lean core, pruned default agents, safer install lifecycle, and cleaner paper discovery — replaced large always-on CLAUDE.md / AGENTS.md files with compact core instructions, pruned the default agent set to the retained core agents, added safe install-state based uninstall support, generalized daily-paper-generator to broader topics with arXiv / bioRxiv support and a fixed Top 10 -> Top 3 -> Top 1 selection flow.
2026-04-15: pubfig and pubtab introduced — introduced pubfig, a Python package for publication-grade scientific figures, and pubtab, a Python package for publication-ready tables and Excel↔LaTeX workflows. Together they provide a cleaner production stack for paper figures, benchmark tables, export control, and final artifact QA.

View older changelog

2026-04-15: publication-chart-skill integrated into Claude Scholar — wrapped pubfig + pubtab into publication-chart-skill, added the skill to the repository, and connected it to Claude Scholar's analysis and writing boundaries so publication-grade figure/table work now has an explicit handoff route instead of being mixed into general analysis or prose skills.
2026-03-31: Zotero smart-import workflow docs aligned — updated Claude Scholar's research-facing docs around the latest zotero-mcp public surface: zotero_add_items_by_identifier is now the default paper-import path, zotero_reconcile_collection_duplicates is the standard post-import cleanup step, source-aware PDF cascade behavior is documented more accurately, and public vs internal diagnostics are now clearly separated.
2026-03-31: README onboarding refreshed — clarified that Claude Scholar is especially well-suited to computer science and AI researchers, added practical getting-started scenarios after installation, improved prerequisite and branch guidance, and made the “existing local md files must be manually merged” expectation much more explicit.
2026-03-31: Installer and hook behavior tightened — the installer now preserves existing local CLAUDE.md while installing the repo-managed version as CLAUDE.scholar.md, and the default hook summaries were trimmed to reduce noisy temp-file / uncommitted-file output while keeping safer write-guard behavior.
2026-03-31: Japanese documentation added — added Japanese docs for the main README plus AGENTS, MCP_SETUP, and OBSIDIAN_SETUP, so the OpenCode branch now has a more complete multilingual documentation surface.
2026-02-25: Codex CLI support — added codex branch supporting OpenAI Codex CLI with config.toml, 40 skills, 14 agents, and sandbox security
2026-02-23: Added setup.sh installer — backup-aware incremental updates for existing ~/.opencode, auto-backup opencode.jsonc, additive agent/mcp/permission/plugin merge
2026-02-21: OpenCode support — Claude Scholar now supports OpenCode as an alternative CLI; switch to the opencode branch for OpenCode-compatible configuration
2026-02-20: Bilingual docs — maintained English and Chinese entry documents for broader readability
2026-02-15: Zotero MCP integration — added /zotero-review and /zotero-notes commands, updated research-ideation skill with Zotero integration guide, enhanced literature-reviewer agent with Zotero MCP support for automated paper import, collection management, full-text reading, and citation export
2026-02-14: Hooks optimization — restructured security-guard to two-tier system (Block + Confirm), skill-forced-eval now groups skills into 6 categories with silent scan mode, session-start limits display to top 5, session-summary adds 30-day log auto-cleanup, stop-summary shows separate added/modified/deleted counts; removed deprecated shell scripts (lib/common.sh, lib/platform.sh)
2026-02-11: Major update — added 10 new skills (research-ideation, results-analysis, citation-verification, review-response, paper-self-review, post-acceptance, daily-coding, frontend-design, ui-ux-pro-max, web-design-reviewer), 7 new agents, 8 research workflow commands, 2 new rules (security, experiment-reproducibility); restructured the main configuration docs; 89 files changed
2026-01-26: Rewrote all Hooks to cross-platform Node.js; completely rewrote README; expanded ML paper writing knowledge base; merged PR #1 (cross-platform support)
2026-01-25: Project open-sourced, v1.0.0 released with 25 skills (architecture-design, bug-detective, git-workflow, kaggle-learner, scientific-writing, etc.), 2 agents (paper-miner, kaggle-miner), 30+ commands (including SuperClaude suite), 5 Shell Hooks, and 2 rules (coding-style, agents)

Quick Navigation

Section	What it helps with
Why Claude Scholar	Understand the project positioning and target use cases.
Core Workflow	See the end-to-end research pipeline from ideation to publication.
Quick Start	Install Claude Scholar in full, minimal, or selective mode.
Getting Started Scenarios	See a few realistic first-use scenarios after installation.
Integrations	Learn how Zotero, Obsidian, and optional X promotion fit into the workflow.
Primary Workflows	Browse the main research and development workflows.
Supporting Workflows	See the background systems that strengthen the main workflow.
Documentation	Jump to setup docs, configuration, and templates.
Citation	Cite Claude Scholar in papers, reports, or project docs.

Why Claude Scholar

Claude Scholar is not an end-to-end autonomous research system that tries to replace the researcher.

Its core idea is simple:

human decision-making stays at the center; the assistant accelerates the workflow around it.

That means Claude Scholar is designed to help with the heavy, repetitive, and structure-sensitive parts of research — literature organization, note-taking, experiment analysis, reporting, and writing support — while still keeping the key judgments in human hands:

which problem is worth pursuing,
which papers actually matter,
which hypotheses are worth testing,
which results are convincing,
and what should be written, submitted, or abandoned.

In other words, Claude Scholar is a semi-automated research assistant, not a “fully automated scientist.”

Who This Is For

Claude Scholar is especially well-suited to:

computer science researchers who move between literature review, coding, experiments, and paper writing,
AI / ML researchers who need one assistant workflow spanning ideation, implementation, analysis, reporting, and rebuttal,
research engineers and graduate students who want stronger workflow structure without giving up human judgment,
and software-heavy academic projects that benefit from Zotero, Obsidian, CLI automation, and reproducible project memory.

It can still help in other research settings, but its current workflow design is most aligned with computer science, AI, and adjacent computational research.

Core Workflow

Claude Scholar routes research work through a traceable path: question -> evidence -> experiment -> analysis -> claim -> writing. Each stage should preserve what is known, what is uncertain, and what decision should happen next.

Ideation: turn a vague topic into concrete questions, research gaps, and an initial plan.
Literature: search, import, organize, and read papers through Zotero collections.
Paper notes: convert papers into structured reading notes and reusable claims.
Knowledge base: route durable knowledge into Obsidian across Sources / Knowledge / Experiments / Results / Results/Reports / Writing / Daily / Maps.
Experiments: track hypotheses, experiment lines, run history, findings, and next actions.
Analysis: generate strict statistics, real scientific figures, and analysis artifacts with results-analysis.
Reporting: produce a complete post-experiment report with results-report, then write it back into Obsidian.
Writing and publication: carry stable findings into literature reviews, papers, rebuttals, slides, posters, and promotion.

Quick Start

Requirements

Claude Code
Git
(Optional) Python + uv for Python development
(Optional) Zotero + Galaxy-Dawn/zotero-mcp for literature workflows
(Optional) Obsidian for project knowledge-base workflows

Option 1: Full Installation (Recommended)

git clone https://github.com/Galaxy-Dawn/claude-scholar.git /tmp/claude-scholar
bash /tmp/claude-scholar/scripts/setup.sh

Windows: please use Git Bash or WSL to run the installer.

The installer is backup-aware and incremental-update friendly:

updates repo-managed skills/commands/agents/rules/hooks/scripts/CLAUDE*.md,
backs up overwritten files to ~/.claude/.claude-scholar-backups/<timestamp>/,
backs up settings.json to settings.json.bak,
preserves an existing ~/.claude/CLAUDE.md and installs the repo-managed version as ~/.claude/CLAUDE.scholar.md,
preserves an existing ~/.claude/CLAUDE.zh-CN.md and installs the repo-managed version as ~/.claude/CLAUDE.zh-CN.scholar.md,
preserves your existing env, model/provider settings, API keys, permissions, and current mcpServers values,
adds missing hook entries instead of replacing your entire hook set.

Important CLAUDE note: if you already maintain your own ~/.claude/CLAUDE.md or ~/.claude/CLAUDE.zh-CN.md, review ~/.claude/CLAUDE.scholar.md and ~/.claude/CLAUDE.zh-CN.scholar.md after installation and manually merge the Claude Scholar sections you want into your own files. Do not assume the sidecar files are applied automatically.

To update later:

cd /tmp/claude-scholar
git pull --ff-only
bash scripts/setup.sh

To uninstall later:

cd /tmp/claude-scholar
bash scripts/uninstall.sh

The installer now writes:

~/.claude/.claude-scholar-manifest.txt for the exact files managed by Claude Scholar
~/.claude/.claude-scholar-install-state for install ownership metadata used by safe uninstall

The uninstaller removes only files and settings entries recorded in that install state. It does not guess ownership from the current repo checkout.

Option 2: Minimal Installation

Install only a small research-focused subset:

git clone https://github.com/Galaxy-Dawn/claude-scholar.git /tmp/claude-scholar
mkdir -p ~/.claude/hooks ~/.claude/skills
cp /tmp/claude-scholar/hooks/*.js ~/.claude/hooks/
cp -r /tmp/claude-scholar/skills/ml-paper-writing ~/.claude/skills/
cp -r /tmp/claude-scholar/skills/research-ideation ~/.claude/skills/
cp -r /tmp/claude-scholar/skills/results-analysis ~/.claude/skills/
cp -r /tmp/claude-scholar/skills/results-report ~/.claude/skills/
cp -r /tmp/claude-scholar/skills/review-response ~/.claude/skills/
cp -r /tmp/claude-scholar/skills/writing-anti-ai ~/.claude/skills/
cp -r /tmp/claude-scholar/skills/git-workflow ~/.claude/skills/
cp -r /tmp/claude-scholar/skills/bug-detective ~/.claude/skills/

Post-install: minimal/manual install does not auto-merge settings.json; copy only the hooks or MCP entries you want from settings.json.template. If you already have your own ~/.claude/CLAUDE.md or ~/.claude/CLAUDE.zh-CN.md, also merge the relevant sections from this repo's Claude files into yours instead of blindly overwriting them.

Option 3: Selective Installation

Copy only the parts you need:

git clone https://github.com/Galaxy-Dawn/claude-scholar.git /tmp/claude-scholar
cd /tmp/claude-scholar

cp hooks/*.js ~/.claude/hooks/
cp -r skills/latex-conference-template-organizer ~/.claude/skills/
cp -r skills/architecture-design ~/.claude/skills/
cp agents/paper-miner.md ~/.claude/agents/
cp rules/coding-style.md ~/.claude/rules/
cp rules/agents.md ~/.claude/rules/

Post-install: selective/manual install does not auto-merge settings.json; copy only the hooks or MCP entries you actually want from settings.json.template. If you already have your own ~/.claude/CLAUDE.md or ~/.claude/CLAUDE.zh-CN.md, merge the relevant sections from this repo's Claude files into yours instead of blindly overwriting them.

Option 4: Plugin Marketplace Installation

Step 1: Install the Plugin

/plugin marketplace add Galaxy-Dawn/claude-scholar
/plugin install claude-scholar@claude-scholar

This auto-loads all skills, commands, agents, and hooks. During installation, you can choose the scope: user (all projects) or project (single project).

Step 2: Install Rules (Required)

Claude Code plugins cannot distribute rules automatically. Install them manually:

git clone https://github.com/Galaxy-Dawn/claude-scholar.git /tmp/claude-scholar

# User-level (all projects)
mkdir -p ~/.claude/rules
cp /tmp/claude-scholar/rules/*.md ~/.claude/rules/

# Or project-level (current project only)
mkdir -p .claude/rules
cp /tmp/claude-scholar/rules/*.md .claude/rules/

Post-install: plugin installation does not auto-load CLAUDE.md or configure settings.json; if you already have your own ~/.claude/CLAUDE.md or ~/.claude/CLAUDE.zh-CN.md, merge the relevant Claude Scholar sections into yours instead of assuming the plugin applies them automatically. If you need Zotero MCP or other integrations, see the Integrations section for manual setup.

Getting Started Scenarios

After installation, the simplest way to begin is to describe your task in natural language. You do not need to memorize the whole system first. Below are a few realistic starting points.

1. Start a New Research Topic

You can say:

Help me start research on [your topic]. I want a literature-grounded plan, the key open questions, and the next concrete steps.

What Claude Scholar will typically help with:

clarify the topic and narrow the research question,
identify promising literature directions,
suggest an initial plan or hypothesis list,
optionally route the work into Zotero or Obsidian if you use them.

2. Review a Zotero Collection

You can say:

Review my Zotero collection on brain foundation models and summarize the main directions, gaps, and promising next steps.

Typical output:

paper grouping by theme,
a short literature synthesis,
gap analysis,
candidate research directions worth pursuing next.

3. Analyze Finished Experiment Results

You can say:

Analyze the results in this experiment folder, check what changed across runs, and write a decision-oriented summary.

Typical output:

metric comparison,
ablation or error-analysis suggestions,
a result summary that highlights what is solid, what is weak, and what to run next.

4. Draft a Paper or Rebuttal Section

You can say:

Help me draft the related work section for this project based on the current findings and paper notes.

or:

Help me write a rebuttal draft for these reviewer comments.

Typical output:

a structured section draft,
improved argument flow,
clearer claims and evidence mapping,
follow-up points that still need support or verification.

Practical Notes

Start with one concrete task, not a vague request for "everything."
If you already maintain your own local CLAUDE.md files, merge the Claude Scholar sections you want into them instead of assuming sidecar files apply automatically.
Zotero and Obsidian are optional, but they become much more useful when you want durable literature notes or project memory rather than one-off chat output.

Platform Support

Claude Scholar is maintained for:

Claude Code — the primary installation target.
Codex CLI — supported workflow and documentation are available in this repo ecosystem.
OpenCode — supported as an alternative CLI workflow.

The top-level workflow is the same: research, coding, experiments, reporting, and project knowledge management.

Integrations

Zotero

Use Zotero when you want Claude Scholar to help with:

paper import via DOI / arXiv / URL,
collection-based reading workflows,
full-text access through Zotero MCP,
detailed paper notes and literature synthesis.

See MCP_SETUP.md.

Obsidian

Use Obsidian when you want Claude Scholar to maintain a filesystem-first research knowledge base:

Sources/
Knowledge/
Experiments/
Results/
Results/Reports/
Writing/
Daily/
Maps/

See OBSIDIAN_SETUP.md.

Xquik (optional)

Use Xquik when /promote needs bounded public X research, draft analysis, or publishing from an approved connected account. Claude Scholar keeps retrieved posts outside scholarly evidence and requires a complete preview plus explicit approval before each write.

See MCP_SETUP.md for client setup and xquik-promotion.md for the promotion workflow.

Primary Workflows

Complete academic research lifecycle — 7 stages from idea to publication.

1. Research Ideation (Zotero-Integrated)

End-to-end research startup from idea generation to literature management.

Type	Name	One-line explanation
Skill	`research-ideation`	Turn vague topics into structured questions, gap analysis, and an initial research plan.
Agent	`literature-reviewer`	Search, classify, and synthesize papers into an actionable literature picture.
Command	`/research-init`	Start a new topic with literature search, Zotero organization, research question cards, and proposal drafting only when the evidence gate passes.
Command	`/zotero-review`	Review an existing Zotero collection and generate a structured literature synthesis.
Command	`/zotero-notes`	Batch-read a Zotero collection and create structured paper reading notes.

How it works

5W1H Brainstorming: turn a vague topic into structured questions (What / Why / Who / When / Where / How).
Literature Search & Import: search papers, extract DOI/arXiv/URLs, import them into Zotero, and organize them into themed collections.
PDF & Full Text: attach PDFs when available, read full text when possible, and fall back to abstract-level analysis when necessary.
Gap Analysis: identify literature, methodological, application, interdisciplinary, or temporal gaps.
Research Question & Planning: convert the review into concrete questions, initial hypotheses, and next-step planning.
Evidence Gate: keep weak sources, project hypotheses, and missing evidence explicit before promoting a claim into Knowledge, Writing, or a proposal.

Typical output

research question cards with hypotheses, evidence needs, falsification criteria, and next actions
literature review notes
structured Zotero collection
project proposal only when the selected question has enough verified evidence; otherwise a research direction / intake draft

2. ML Project Development

Maintainable ML project structure for experiment code and iteration.

Type	Name	One-line explanation
Skill	`architecture-design`	Define maintainable ML project structure when new registrable components or modules are introduced.
Skill	`git-workflow`	Enforce branch hygiene, commit conventions, and safer collaboration workflows.
Skill	`bug-detective`	Debug stack traces, shell failures, and code-path issues systematically.
Agent	`code-reviewer`	Review modified code for correctness, maintainability, and implementation quality.
Agent	`tdd-guide`	Provide focused test-driven implementation guidance when a TDD path is explicitly needed.
Command	`/plan`	Create or refine an implementation plan before coding.
Command	`/commit`	Prepare a conventional commit for the current changes.
Command	`/code-review`	Run a focused review on the current code changes.
Command	`/tdd`	Drive feature work through small, test-backed implementation steps.

How it works

Structure: use Factory / Registry patterns for new ML components when appropriate.
Code Quality: keep files maintainable, typed, and config-driven.
Debugging: inspect stack traces, shell failures, and code-path issues systematically.
Git Discipline: use branch hygiene, conventional commits, and safer merge/rebase workflows.

3. Experiment Analysis

Strict analysis of experimental results with scientific figures and report-ready artifacts.

Type	Name	One-line explanation
Skill	`results-analysis`	Produce a strict analysis bundle with rigorous statistics, real scientific figures, and analysis artifacts.
Skill	`results-report`	Turn analysis artifacts into a complete post-experiment report with decisions, limitations, and next actions.
Command	`/analyze-results`	Run a blocker-first experiment workflow: validate evidence, run strict analysis when possible, then generate a report only when the bundle is sufficient.

How it works

Data Processing: read experiment logs, metrics files, and result directories.
Blocker-First Gate: lock unit of analysis, primary metric, seeds/folds/runs, provenance, and comparison family before producing claims.
Statistical Testing: run strict statistical checks such as t-test / ANOVA / Wilcoxon where appropriate.
Visualization: generate real scientific figures with interpretation guidance, not just vague plotting suggestions.
Ablation & Comparison: analyze component contribution, performance tradeoffs, and stability.
Post-Experiment Reporting: turn the analysis bundle into a full retrospective report with conclusions, limitations, and next actions.

Typical output

analysis-report.md
stats-appendix.md
figure-catalog.md
figures/
post-experiment summary report in Obsidian Results/Reports/
blocker summary / audit note when evidence is incomplete

4. Paper Writing

Systematic academic writing from structure setup to draft refinement.

Type	Name	One-line explanation
Skill	`ml-paper-writing`	Draft publication-oriented ML/AI papers from repo context, evidence, and literature.
Skill	`nature-writing`	Draft or rebuild Nature-style manuscript sections from claims, figures, results, notes, or Chinese drafts.
Skill	`nature-polishing`	Polish, restructure, or translate manuscript prose into concise Nature-leaning English.
Skill	`nature-response`	Draft, audit, or revise point-by-point reviewer response letters for Nature-family revisions.
Skill	`nature-data`	Prepare Nature-ready Data Availability statements, repository plans, and FAIR metadata checks.
Skill	`citation-verification`	Check references, metadata, and claim-citation alignment to prevent citation mistakes.
Skill	`writing-anti-ai`	Reduce robotic phrasing and improve clarity, rhythm, and human academic tone.
Skill	`latex-conference-template-organizer`	Clean messy conference templates into an Overleaf-ready writing structure.
Agent	`paper-miner`	Mine strong papers for reusable writing patterns, structure, and venue expectations.
Command	`/mine-writing-patterns`	Read a paper and merge reusable writing knowledge into the active installed paper-miner writing memory.

The mined memory is shared by ml-paper-writing, Nature writing and polishing, and reviewer-response skills. Re-running scripts/setup.sh preserves the active memory, and uninstall leaves it in place. Back up that file before updating skills with a manual cp -r.

How it works

Template Preparation: clean conference templates into an Overleaf-ready structure.
Journal-Style Polishing: tighten paragraph logic, hedging, and section moves for Nature-leaning prose when needed.
Reviewer Response: structure major/minor revision comments into an auditable point-by-point response package.
Data Availability: prepare Nature-ready repository plans, dataset citations, and availability statements.
Citation Verification: verify references, metadata, and claim-citation alignment.
Systematic Writing: draft sections from repo context, experiment evidence, and literature notes, while keeping unsupported claims marked instead of polished.
Claim Ledger: every contribution, result, and contrast should trace to evidence or remain explicitly speculative.
Style Refinement: reduce robotic phrasing and improve rhythm, clarity, and tone.

5. Paper Self-Review

Quality assurance before submission.

Type	Name	One-line explanation
Skill	`paper-self-review`	Audit structure, logic, citations, figures, and compliance before submission.

How it works

Structure Check: logical flow, section balance, and narrative coherence.
Logic Validation: claim-evidence alignment, assumption clarity, and argument consistency.
Claim Audit: verify that main claims are supported by evidence, weaken over-strong language, and preserve uncertainty when needed.
Citation Audit: reference correctness and completeness.
Figure Quality: caption completeness, readability, and accessibility.
Compliance: page limits, formatting, and disclosure requirements.

6. Submission & Rebuttal

Submission preparation and review response workflow.

Type	Name	One-line explanation
Skill	`review-response`	Structure reviewer comments into an evidence-based rebuttal workflow.
Agent	`rebuttal-writer`	Optional specialist for professional, respectful, and strategically organized rebuttal text when available.
Command	`/rebuttal`	Generate an evidence-anchored rebuttal draft from review comments, with unresolved points marked instead of hidden.

How it works

Pre-submission Checks: venue-specific formatting, anonymization, and checklist requirements.
Review Analysis: classify reviewer comments into actionable categories.
Response Strategy: decide whether to accept, defend, clarify, or propose new experiments.
Rebuttal Writing: generate structured responses with professional tone, evidence anchors, and explicit unresolved items.

7. Post-Acceptance Processing

Conference preparation and research promotion after acceptance.

Type	Name	One-line explanation
Skill	`post-acceptance`	Support talks, posters, and research promotion after acceptance.
Command	`/presentation`	Generate presentation structure and speaking guidance for the accepted work.
Command	`/poster`	Organize the work into poster-ready content and layout guidance.
Command	`/promote`	Draft public-facing promotion content such as summaries, posts, or threads.

How it works

Presentation: prepare talk structure and slide guidance.
Poster: organize content into poster-ready layout and hierarchy.
Promotion: verify claims, draft by platform, and optionally use Xquik for bounded X research or approved publishing.

Supporting Workflows

These workflows run in the background to strengthen the primary workflows.

Obsidian Project Knowledge Base

Use Obsidian as the project-scoped durable knowledge surface, not just as a note dump.

Type	Name	One-line explanation
Skill	`obsidian-project-kb-core`	Main authority for project-scoped KB bootstrap, routing, registry, index, daily, and lifecycle updates.
Skill	`obsidian-source-ingestion`	Ingest external material into `Sources/Papers`, `Sources/Web`, `Sources/Docs`, `Sources/Data`, `Sources/Interviews`, or `Sources/Notes`.
Skill	`obsidian-literature-workflow`	Run the paper-note to synthesis workflow from `Sources/Papers` into `Knowledge`, `Writing`, and `Maps/literature.canvas`.
Skill	`obsidian-kb-artifacts`	Handle Obsidian-native artifacts such as wikilinks, registry tables, canvas files, optional Bases, and link repair.
Command	`/kb-init`	Initialize the vault-first KB under `Research/{project-slug}/`.
Command	`/kb-status`	Summarize the current KB state from the bound project root.
Command	`/kb-ingest`	Route new source material into the correct canonical KB destination.
Command	`/kb-log`	Update the current Daily note and related project surfaces conservatively.
Command	`/kb-sync`	Run deterministic KB maintenance to refresh registry, index, daily, and runtime binding state.
Command	`/kb-links`	Repair or strengthen wikilinks among canonical KB notes.
Command	`/kb-promote`	Promote durable content from Daily or source notes into canonical notes.
Command	`/kb-index`	Regenerate `02-Index.md` as the human-readable project navigator.
Command	`/kb-lint`	Run deterministic KB health checks and update `_system/lint-report.md`.
Command	`/kb-archive`	Archive, detach, purge, or rename KB objects while keeping links and registry consistent.
Command	`/kb-map`	Generate or repair explicit-only KB artifacts beyond the default literature canvas.
Command	`/kb-literature-review`	Generate evidence-gated literature synthesis from `Sources/Papers` into `Knowledge`, optional `Writing`, and `Maps/literature.canvas`.

How it works

bind an existing repo to an Obsidian vault,
route stable knowledge into Sources / Knowledge / Experiments / Results / Results/Reports / Writing / Daily / Maps,
keep Daily/ and repo-local binding metadata updated conservatively,
ingest new source material into the correct canonical destination,
keep abstract-only and webpage-placeholder sources from supporting durable claims,
only generate extra Bases or canvases on explicit request.
use /kb-sync for deterministic resyncs and /kb-links for standalone link repair.

Note language configuration

Generated and synced Obsidian notes resolve their language with this priority:

project config: .claude/project-memory/registry.yaml -> note_language
environment variable: OBSIDIAN_NOTE_LANGUAGE
default: en

Note: the file is currently named registry.yaml for historical reasons, but its on-disk format is JSON.

Per-project example:

{
  "projects": {
    "my-project": {
      "project_id": "my-project",
      "vault_root": "/path/to/vault/Research/my-project",
      "note_language": "zh-CN"
    }
  }
}

English and Chinese section headings remain mutually compatible during sync, so older notes in either language can still be updated safely after switching configuration.

Automated Enforcement Workflow

Cross-platform hooks automate routine workflow checks and reminders.

Hooks

skill-forced-eval.js
session-start.js
session-summary.js
stop-summary.js
security-guard.js

How it works

Before prompts: evaluate applicable skills and surface relevant workflow hints.
At session start: show Git state, available commands, and project-memory context.
At session end/stop: summarize work and remind the user about minimum maintenance tasks.
Security: block catastrophic commands and require confirmation for dangerous but legitimate ones.

Communication and Reporting Discipline

Use a reusable communication layer when the task needs conclusion-first reporting, concrete evidence, visible risk, or compact next-step guidance.

Type	Name	One-line explanation
Skill	`expression-skill`	Enforces conclusion-first, concrete, checkable communication for technical work, writing, documentation, file operations, and multi-step tasks.
Skill	`planning-with-files`	Makes complex work persistent on disk with `task_plan.md`, `notes.md`, and deliverable files instead of relying only on transient chat context.

How it works

lead with the conclusion instead of narration,
prefer commands, paths, counts, checks, and observable behavior over abstract process language,
ask clarifying questions only when ambiguity changes the outcome,
surface risk, uncertainty, and destructive boundaries early,
keep long-running work visible with step / checkpoint style roadmarks,
persist multi-step work to disk with task_plan.md and notes.md instead of relying only on transient context.

Knowledge Extraction Workflow

Specialized agents can mine reusable knowledge from papers and competitions.

Type	Name	One-line explanation
Agent	`paper-miner`	Extract reusable writing knowledge, structure patterns, and venue heuristics from strong papers.
Agent	`kaggle-miner`	Extract engineering practices and solution patterns from strong Kaggle workflows.

How it works

extract writing patterns, venue expectations, and rebuttal strategies from papers,
extract engineering patterns and solution structure from Kaggle workflows,
feed those insights back into skills and reference material.

Skill Evolution System

Claude Scholar also contains a self-improvement loop for its own skills.

Type	Name	One-line explanation
Skill	`skill-development`	Create new skills with clear triggers, structure, and progressive disclosure.
Skill	`skill-quality-reviewer`	Review skills across content quality, organization, style, and structural integrity.
Skill	`skill-improver`	Apply structured improvement plans to evolve existing skills.

How it works

create new skills with clear trigger descriptions,
review them across quality dimensions,
apply structured improvements and iterate.

Documentation

MCP_SETUP.md — Zotero/browser MCP setup
OBSIDIAN_SETUP.md — Obsidian knowledge base workflow
CLAUDE.md — lightweight Claude Code core instructions
CLAUDE.zh-CN.md — Chinese companion for the lightweight core instructions
settings.json.template — optional settings template for hooks/plugins/MCP

Project Rules

Claude Scholar includes project rules for:

coding style,
agent orchestration,
security,
experiment reproducibility.

These are reflected in the shipped rules and in CLAUDE.md.

Contributing

Issues, PRs, and workflow improvements are welcome.

If you propose changes to installer behavior, Zotero workflows, or Obsidian routing, please include:

the user scenario,
the current limitation,
the expected behavior,
and any compatibility concerns.

License

MIT License.

Citation

If Claude Scholar helps your research or engineering workflow, you can cite the repository as:

@misc{claude_scholar_2026,
  title        = {Claude Scholar: Semi-automated research assistant for academic research and software development},
  author       = {Gaorui Zhang},
  year         = {2026},
  howpublished = {\url{https://github.com/Galaxy-Dawn/claude-scholar}},
  note         = {GitHub repository}
}

Acknowledgments

Built with Claude Code CLI and enhanced by the open-source community.

References

This project is inspired by and builds upon excellent work from the community:

everything-claude-code - Comprehensive resource for Claude Code CLI
AI-research-SKILLs - Research-focused skills and configurations
expression-skill - Public conclusion-first communication skill reused here for reporting and response discipline
nature-skills - Nature-oriented writing, polishing, reviewer-response, and data-availability skills reused here with attribution

These projects provided valuable insights and foundations for the research-oriented features in Claude Scholar.

For data science, AI research, and academic writing.

Repository: https://github.com/Galaxy-Dawn/claude-scholar

Agent Skills 是什么？

Skill 就是一个装着 SKILL.md 的文件夹：头信息写 name 和 description，正文写具体指令；Agent 平时只记描述，匹配请求后再读全文。

快速上手：装第一个 Skill

在技能库挑一条接近任务的 Skill，按详情里的安装说明放到 Agent 目录，用点名或自然语言触发一次并核对结果。

Skills 和 Prompt 怎么选？

只复制一段指令就用 Prompt；要让 Agent 按固定步骤、检查清单或脚本反复完成同一类任务，再用 Skill。

Skills 和 MCP 有什么区别？

Skill 教 Agent 一套做法；MCP 把外部数据和工具接进 Agent。很多工作流两样都要。

按任务挑 Skill，不按名字挑

先写清要完成的事，再在技能库里对 description；再看安装成本、维护状态和权限范围。

Sponsor	Description
	OfoxAI: Model APIs for research, code and writing: Access Claude, GPT, Gemini and DeepSeek text models with one API key for literature reading, experiment code and academic writing. Image, video and speech models are also available for research presentations and communication.
	Thanks to APIMart for sponsoring this project! APIMart is a low-cost API platform for AI image & video generation — GPT-Image-2 from $0.006/image, 160+ images per dollar. One async API covers both image and video: submit a task, get an ID, fetch results via polling or callback. Batch tens of thousands of images without timeouts, switch models without changing code. Pay-as-you-go with no monthly fee — sign up here to get started.
	Thanks to the Kimi team for their strong support of this project! Official links: Kimi Code · Platform CN · Platform Global.

文件

Agent Development for Claude Code Plugins

Overview

When to Use

When Not to Use

Agent File Structure

Complete Format

Frontmatter Fields

name (required)

description (required)

model (required)

color (required)

tools (optional)

System Prompt Design

Structure

Best Practices

Creating Agents

Method 1: AI-Assisted Generation

Method 2: Manual Creation

Validation Rules

Identifier Validation

Description Validation

System Prompt Validation

Agent Organization

Plugin Agents Directory

Namespacing

Testing Agents

Test Triggering

Test System Prompt

Quick Reference

Minimal Agent

Frontmatter Fields Summary

Best Practices

Additional Resources

Reference Files

Example Files

Utility Scripts

Implementation Workflow

Sponsors

Recent News

Quick Navigation

Why Claude Scholar

Who This Is For

Core Workflow

Quick Start

Requirements

Option 1: Full Installation (Recommended)

Option 2: Minimal Installation

Option 3: Selective Installation

Option 4: Plugin Marketplace Installation

Getting Started Scenarios

1. Start a New Research Topic

2. Review a Zotero Collection

3. Analyze Finished Experiment Results

4. Draft a Paper or Rebuttal Section

Practical Notes

Platform Support

Integrations

Zotero

Obsidian

Xquik (optional)

Primary Workflows

1. Research Ideation (Zotero-Integrated)

2. ML Project Development

3. Experiment Analysis

4. Paper Writing

5. Paper Self-Review

6. Submission & Rebuttal

7. Post-Acceptance Processing

Supporting Workflows

Obsidian Project Knowledge Base

Automated Enforcement Workflow

Communication and Reporting Discipline

Knowledge Extraction Workflow

Skill Evolution System

Documentation

Project Rules

Contributing

License

Citation