v0.2.4 support pip-installed skill defaults

Package built-in EasyPaper skill YAMLs for pip users, synchronize the Claude Code configuration template with the project example, and avoid requiring FastAPI for SDK-only imports.

Constraint: pip-installed users must be able to enable skills without cloning the repository skills directory.

Constraint: Claude Code plugin configuration should match configs/example.yaml.

Rejected: Add FastAPI to base dependencies | SDK-only users should not pay for optional server dependencies.

Confidence: high

Scope-risk: moderate

Directive: Keep root skills/ and src/skills/builtin synchronized before release packaging.

Tested: pytest tests -q (1043 passed, 9 skipped)

Tested: clean venv local pip install without fastapi, SDK import and EasyPaper config init

Tested: targeted router and SDK regression tests; compileall; git diff --check; ruff F821 on affected files

Co-authored-by: OmX <omx@oh-my-codex.dev>

Author: Yuwei Yan

.claude-plugin/README.md

@@ -35,7 +35,12 @@ This will guide you through an interactive workflow to generate your academic pa
 
 ## Configuration
 
-Create a YAML config file (see `configs/example.yaml` in the project) with your API keys:
+If you do not already have a config, run `/easypaper-setup`. The setup skill
+creates `easypaper_config.yaml` from its bundled `config.example.yaml`, which is
+kept synchronized with the current EasyPaper `configs/example.yaml` template.
+You only need to replace the API key placeholders.
+
+For reference, a minimal agent entry looks like:
 
 ```yaml
 agents:

configs/example.yaml

@@ -6,7 +6,7 @@ skills:
     - '*'
   # venue_profile: "neurips"
 
-  # Tools configuration for ReAct-enabled agents (MetaDataAgent, WriterAgent)
+# Tools configuration for ReAct-enabled agents (MetaDataAgent, WriterAgent)
 tools:
   enabled: true
   planner_structure_signals_enabled: true # Planner emits soft structure signals

easypaper/client.py

@@ -28,7 +28,8 @@
 from typing import Any, AsyncGenerator, Dict, Optional
 
 from src.config.loader import load_config
-from src.config.schema import AppConfig, SkillsConfig
+from src.config.schema import AppConfig
+from src.skills.bootstrap import bootstrap_skill_registry_for_config, format_skill_load_report
 from src.agents import initialize_agents
 from src.agents.shared.docling_service import DoclingService
 from src.agents.shared.docling_analyzer import DoclingPaperResult
@@ -281,24 +282,15 @@ def _build_agents(config: AppConfig) -> Dict[str, Any]:
         - **Returns**:
             - `Dict[str, BaseAgent]`: Agent name -> instance mapping.
         """
-        skill_registry = None
-        skills_config = config.skills or SkillsConfig(enabled=False)
-        if skills_config.enabled:
-            try:
-                from src.skills.loader import SkillLoader
-                from src.skills.registry import SkillRegistry
-                skill_registry = SkillRegistry()
-                loader = SkillLoader()
-                for skill in loader.load_directory(Path(skills_config.skills_dir)):
-                    skill_registry.register(skill)
-                logger.info("Skills: loaded %d skills", len(skill_registry))
-            except Exception:
-                logger.warning("Skills loading failed; continuing without skills")
-                skill_registry = None
+        skill_registry, skills_config, skill_report = bootstrap_skill_registry_for_config(
+            config.skills
+        )
+        logger.info("Skills: %s", format_skill_load_report(skill_report))
 
         agents = initialize_agents(
             config.agents,
             skill_registry=skill_registry,
+            skills_config=skills_config if skill_registry is not None else None,
             global_tools_config=config.tools,
             vlm_service_config=config.vlm_service,
         )

plugins/easypaper/.claude-plugin/README.md

@@ -62,7 +62,12 @@ pip install easypaper
 
 ## Configuration
 
-Create a YAML config file (see `configs/example.yaml` in the project) with your API keys:
+If you do not already have a config, run `/easypaper-setup`. The setup skill
+creates `easypaper_config.yaml` from its bundled `config.example.yaml`, which is
+kept synchronized with the current EasyPaper `configs/example.yaml` template.
+You only need to replace the API key placeholders.
+
+For reference, a minimal agent entry looks like:
 
 ```yaml
 agents:

plugins/easypaper/commands/easypaper-paper-from-metadata.md

@@ -59,7 +59,7 @@ options = {
     "artifacts_prefix": request.artifacts_prefix or "",
 }
 
-result = await EasyPaper(config_path=str(Path("configs/openrouter.yaml").resolve())).generate(
+result = await EasyPaper(config_path=str(Path("easypaper_config.yaml").resolve())).generate(
     metadata,
     **options,
 )
@@ -86,7 +86,9 @@ result = await EasyPaper(config_path=str(Path("configs/openrouter.yaml").resolve
 - Missing required fields: collect missing information interactively.
 - Invalid metadata format: show validation errors and reference `examples/meta.json`.
 - Package not installed: use `easypaper-setup-environment`.
-- Config missing: ask for config path or use the default config path if present.
+- Config missing: use `easypaper-setup-environment` to create
+  `easypaper_config.yaml` from the synchronized skill-bundled template, or ask
+  for an explicit config path.
 - Final PDF selection: prefer `result.pdf_path`, then `iteration_*_final/**/*.pdf`, latest `iteration_*`, then `paper.pdf`.
 
 $ARGUMENTS

plugins/easypaper/commands/easypaper-setup.md

@@ -5,12 +5,15 @@ Set up EasyPaper environment including Python dependencies and LaTeX toolchain.
 1. Use the `easypaper-setup-environment` skill to:
    - Create isolated virtual environment (prefer `uv`, fallback to `venv`)
    - Install easypaper package
+   - Create or validate `easypaper_config.yaml` from the skill-bundled
+     `config.example.yaml` template when the user does not already have config
    - Check LaTeX installation and provide installation instructions if missing
    - Verify all components are working
 
 2. After setup, provide clear instructions on:
    - How to activate the environment
    - How to use EasyPaper as Python SDK: `from easypaper import EasyPaper, PaperMetaData`
-   - Next steps for using the plugin (need config file with API keys)
+   - Which config path will be used for generation
+   - Next steps for using the plugin
 
 $ARGUMENTS

plugins/easypaper/commands/easypaper.md

@@ -6,8 +6,10 @@ Run the EasyPaper end-to-end paper generation workflow with guided setup and met
 
 1. Check whether EasyPaper is usable:
    - `.easypaper-env` exists, or `python -c "import easypaper"` succeeds
+   - A usable EasyPaper config exists at a user-provided path, `AGENT_CONFIG_PATH`,
+     `./easypaper_config.yaml`, `./configs/openrouter.yaml`, or `./configs/example.yaml`
    - `pdflatex` is available when the user wants PDF output
-2. If not ready, use the `easypaper-setup-environment` skill to create an isolated environment, install EasyPaper, and guide LaTeX setup.
+2. If not ready, use the `easypaper-setup-environment` skill to create an isolated environment, install EasyPaper, create/validate configuration from the synchronized template, and guide LaTeX setup.
 
 ### Phase 2: Choose metadata source
 
@@ -40,7 +42,7 @@ import json
 from pathlib import Path
 from easypaper import EasyPaper, PaperGenerationRequest
 
-config_path = Path("configs/openrouter.yaml").resolve()
+config_path = Path("easypaper_config.yaml").resolve()
 request = PaperGenerationRequest.model_validate(
     json.loads(Path("metadata.json").read_text(encoding="utf-8"))
 )

plugins/easypaper/skills/easypaper-paper-from-metadata/SKILL.md

@@ -52,7 +52,7 @@ options = {
     "artifacts_prefix": request.artifacts_prefix or "",
 }
 
-ep = EasyPaper(config_path=str(Path("configs/openrouter.yaml").resolve()))
+ep = EasyPaper(config_path=str(Path("easypaper_config.yaml").resolve()))
 result = await ep.generate(paper_metadata, **options)
 ```
 
@@ -149,6 +149,9 @@ Folder-generated metadata:
 
 Config:
 - Resolve `config_path` before constructing `EasyPaper`.
+- Prefer the setup-generated `./easypaper_config.yaml`. If it is missing,
+  run `easypaper-setup-environment` so Claude can create it from the
+  synchronized skill-bundled `config.example.yaml` template.
 
 ## Alternative: Generate Metadata from a Materials Folder
 
@@ -158,7 +161,7 @@ When the user has a folder of research materials instead of a ready metadata JSO
 from pathlib import Path
 from easypaper import EasyPaper
 
-ep = EasyPaper(config_path=str(Path("configs/openrouter.yaml").resolve()))
+ep = EasyPaper(config_path=str(Path("easypaper_config.yaml").resolve()))
 
 metadata = await ep.generate_metadata_from_folder(
     str(Path("path/to/materials").resolve()),

plugins/easypaper/skills/easypaper-setup-environment/SKILL.md

@@ -39,23 +39,52 @@ Use this skill when the plugin is first installed or when environment setup is n
 - Verify installation by running: `pdflatex --version`
 - If not installed, provide clear installation instructions for the user's OS
 
-### 4. Verify Setup
+### 4. Create or Validate Configuration
+
+- Check for an existing EasyPaper YAML config in this order:
+  - User-provided path in the conversation
+  - `AGENT_CONFIG_PATH`
+  - `./easypaper_config.yaml`
+  - `./configs/openrouter.yaml`
+  - `./configs/example.yaml`
+- If no usable config exists, create `./easypaper_config.yaml` from the bundled
+  sibling template file `config.example.yaml`.
+- The bundled `config.example.yaml` must stay byte-for-byte synchronized with
+  the repository source template `configs/example.yaml`; do not hand-write a
+  partial config in this skill.
+- After creating the file, ask the user for the required LLM API key/provider
+  value and replace only the placeholder values they explicitly provide
+  (for example `YOUR_OPENROUTER_KEY`). Do not invent credentials.
+- Keep the generated config path explicit for later SDK calls, either by using
+  `EasyPaper(config_path="<absolute path to easypaper_config.yaml>")` or by
+  setting `AGENT_CONFIG_PATH` for commands that call `load_config()`.
+- The template enables the skills system. Users do not need a local `./skills`
+  folder: EasyPaper loads packaged built-in skills first, then overlays user
+  skills from `skills_dir` when that directory exists.
+
+### 5. Verify Setup
 
 - Test EasyPaper import: `python -c "import easypaper; from easypaper import EasyPaper, PaperMetaData; print('EasyPaper imported successfully')"`
 - Test LaTeX: `pdflatex --version`
+- Test config parsing when a config path exists:
+  `python -c "from easypaper import EasyPaper; EasyPaper(config_path='easypaper_config.yaml'); print('EasyPaper config loaded successfully')"`
 
-### 5. Create Environment Activation Script
+### 6. Create Environment Activation Script
 
 Create a helper script (`.easypaper-activate.sh` or `.easypaper-activate.bat`) that:
 - Activates the virtual environment
 - Sets up PATH if needed
 - Provides instructions for using EasyPaper as Python SDK
+- Exports `AGENT_CONFIG_PATH` to the generated config path when practical
 
 ## Error Handling
 
 - If Python version < 3.11, inform user and suggest upgrade
 - If package installation fails, show error and suggest manual installation
 - If LaTeX is missing, provide OS-specific installation commands
+- If the config template file is missing from the installed skill directory,
+  report the plugin installation as incomplete and ask the user to reinstall
+  the EasyPaper Claude Code plugin.
 - Always verify each step before proceeding to the next
 
 ## Post-Setup Instructions
@@ -65,4 +94,4 @@ After successful setup, inform the user:
 2. To activate: `source .easypaper-env/bin/activate` (or equivalent for Windows)
 3. EasyPaper can now be used directly as a Python SDK: `from easypaper import EasyPaper, PaperMetaData`
 4. The environment is isolated and won't affect system Python
-5. Make sure you have a config file (YAML) with your API keys - see `configs/example.yaml` for reference
+5. The active config file path, normally `./easypaper_config.yaml`

plugins/easypaper/skills/easypaper-setup-environment/config.example.yaml

@@ -0,0 +1,148 @@
+# Skills system configuration
+skills:
+  enabled: true
+  skills_dir: ./skills
+  active_skills:
+    - '*'
+  # venue_profile: "neurips"
+
+# Tools configuration for ReAct-enabled agents (MetaDataAgent, WriterAgent)
+tools:
+  enabled: true
+  planner_structure_signals_enabled: true # Planner emits soft structure signals
+  table_critic_enabled: true # Enable critic-gated table schema restructuring when justified
+  table_critic_max_iterations: 2 # Max critic/rewrite rounds for table restructuring
+  table_rendered_review_enabled: true # Run final rendered VLM/layout review for table formatting
+  writer_structure_contract_enabled: true # Inject structure quality contract into Writer prompts
+  review_structure_gate_enabled: true # Enforce structure quality gate in Reviewer
+  structure_gate_min_paragraph_threshold: 5 # Trigger gate for dense sections
+  available_tools:
+    - validate_citations
+    - count_words
+    - check_key_points
+    - search_papers
+  max_react_iterations: 3
+  paper_search:
+    # Optional API keys. Leave null/omitted to use anonymous/fallback search.
+    # semantic_scholar_api_key improves Semantic Scholar rate limits.
+    semantic_scholar_api_key: null
+    timeout: 15
+    search_results_per_round: 12 # Papers to return per search round
+    planner_max_queries_per_section: 5 # Max query rounds per section
+    planner_inter_round_delay_sec: 1.5 # Delay between rounds to reduce 429
+    planner_min_target_papers_per_section: 3 # Minimum discovered refs per section
+    semantic_scholar_min_results_before_fallback: 3 # Fallback to arXiv when SS results are low
+    enable_query_cache: true # Reuse repeated query results during service runtime
+    cache_ttl_hours: 24 # Cache TTL for repeated queries
+    citation_budget_enabled: true # Let planner decide per-section citation budgets
+    citation_budget_soft_cap: true # Prefer budgeted refs, allow small overflow
+    citation_budget_export: true # Export budget plan/usage artifacts
+    citation_budget_reserve_size: 4 # Overflow reserve keys per section
+    planner_landscape_max_queries: 8 # Pre-plan broad literature search for research context
+    planner_max_utility_searches: 12 # Dataset / metric / framework triggers after plan
+  research_context:
+    enabled: true # Generate research context summary
+    detailed: true # Detailed mode with trends and gaps
+    top_k_key_papers: 10 # Number of key papers to include (also caps landscape pool for context LLM)
+    claim_evidence_enabled: true # Generate claim-to-evidence mappings
+    contribution_ranking_enabled: true # Generate P0/P1/P2 contribution priorities
+    export_planning_decision_trace: false # Export explicit planning decision trace (debug)
+  core_ref_analysis:
+    enabled: true # LLM deep analysis of user core refs; false uses heuristic fallback only
+    max_abstract_chars: 2000
+    analyze_cross_paper: true
+  docling:
+    enabled: true
+    device: auto
+    do_ocr: false
+    do_table_structure: true
+    do_formula_enrichment: false
+    max_pages: 30
+    download_timeout: 30
+    cleanup_after_analysis: true
+  exemplar:
+    enabled: true
+    prefer_core_refs: true
+    venue_match_required: true
+    recency_years: 5
+    max_external_candidates: 10
+    max_analysis_chars: 8000
+
+agents:
+  - name: paper_parser
+    model:
+      model_name: google/gemini-3-flash-preview
+      api_key: YOUR_OPENROUTER_KEY
+      base_url: https://openrouter.ai/api/v1
+
+  - name: template_parser
+    model:
+      model_name: google/gemini-3-flash-preview
+      api_key: YOUR_OPENROUTER_KEY
+      base_url: https://openrouter.ai/api/v1
+
+  - name: commander
+    model:
+      model_name: google/gemini-3-flash-preview
+      api_key: YOUR_OPENROUTER_KEY
+      base_url: https://openrouter.ai/api/v1
+
+  - name: writer
+    model:
+      model_name: google/gemini-3-flash-preview
+      api_key: YOUR_OPENROUTER_KEY
+      base_url: https://openrouter.ai/api/v1
+    writer_config:
+      max_review_iterations: 2
+      enable_review: true
+      enable_tools: true
+      available_tools:
+        - validate_citations
+        - count_words
+        - check_key_points
+
+  - name: typesetter
+    model:
+      model_name: google/gemini-3-flash-preview
+      api_key: YOUR_OPENROUTER_KEY
+      base_url: https://openrouter.ai/api/v1
+
+  - name: metadata
+    model:
+      model_name: google/gemini-3-flash-preview
+      api_key: YOUR_OPENROUTER_KEY
+      base_url: https://openrouter.ai/api/v1
+    metadata_config:
+      enable_mini_review: true
+      max_review_iterations: 2
+
+  - name: reviewer
+    model:
+      model_name: google/gemini-3-flash-preview
+      api_key: YOUR_OPENROUTER_KEY
+      base_url: https://openrouter.ai/api/v1
+
+  - name: planner
+    model:
+      model_name: google/gemini-3-flash-preview
+      api_key: YOUR_OPENROUTER_KEY
+      base_url: https://openrouter.ai/api/v1
+
+  - name: vlm_review
+    vlm_review_config:
+      enabled: true
+      render_dpi: 150
+      max_pages_to_analyze: 12
+      check_overflow: true
+      check_underfill: true
+      check_layout: true
+      min_fill_percentage: 0.85
+      max_blank_area: 0.15
+
+# Shared VLM service (PlannerAgent for figure/table analysis, VLMReviewAgent for PDF page analysis)
+vlm_service:
+  enabled: true
+  provider: openai
+  model: openai/gpt-4o
+  api_key: YOUR_OPENROUTER_KEY
+  base_url: https://openrouter.ai/api/v1