research-en/README.md

research-en

Claude Code skill bundle for structured, resumable, parallel deep research. Five user-invocable slash commands take a topic from a back-of-the-envelope idea to a finished Markdown report, with web search, per-item parallel agents, JSON validation, and field-by-field coverage checks.

English variant. The bundle ships five skills that share a single project directory layout (./{topic_slug}/) and YAML/JSON contract.

Pipeline

/research <topic>           →  outline.yaml + fields.yaml
        ↓
/research-add-items         (optional, supplement items)
/research-add-fields        (optional, supplement fields)
        ↓
/research-deep              →  results/*.json  (one per item, parallel agents)
        ↓
/research-report            →  generate_report.py + report.md

Skills

Skill	Trigger	What it does
research	/research <topic>	Step 1 — generate initial item list + field framework from model knowledge; Step 2 — launch 1 background web-search-agent to supplement; Step 3 — merge user's existing fields if any; Step 4 — write outline.yaml (items + execution config) and fields.yaml (field defs with `detail_level: brief
research-add-items	/research-add-items	Append new research objects to outline.yaml (user input + optional web search), dedup, in-place update.
research-add-fields	/research-add-fields	Append new field definitions to fields.yaml (user input + optional web search), category + detail_level confirmed by user.
research-deep	/research-deep	Auto-locate outline.yaml, resume from completed JSONs, batch-launch background web-search-agents (items_per_agent per agent, batch_size parallel), each writes {output_dir}/{item_slug}.json per fields.yaml, validates with validate_json.py.
research-report	/research-report	Read all JSONs + fields.yaml, ask which numeric fields to surface in the TOC, generate generate_report.py (handles flat/nested JSON, multi-language category mapping, complex-value formatting, uncertain skipping), execute it to produce report.md.

File contracts

outline.yaml

topic: <research topic>
items:
  - name: <item name>
    category: <category>
    description: <brief>
execution:
  batch_size: <parallel agents>
  items_per_agent: <items per agent>
  output_dir: ./results

fields.yaml

field_categories:
  - category: Basic Info
    fields:
      - name: <field>
        description: <field description>
        detail_level: brief | moderate | detailed
        required: true | false
uncertain: []   # reserved, populated during deep phase

results/{item_slug}.json

{
  "name": "...",
  "release_date": "...",
  "underlying_model": "[uncertain]",
  "uncertain": ["underlying_model", ...]
}

Both flat ({"name": ...}) and nested ({"basic_info": {"name": ...}}) layouts are supported throughout.

Validation

Every deep-research agent finishes with:

python research/validate_json.py -f <fields.yaml> -j <result.json>

validate_json.py reports per-file:

• coverage % (covered / defined fields)
• missing required (FAIL if non-empty)
• missing optional, grouped by category
• extra fields not defined in fields.yaml

Exit code is non-zero if any required field is missing.

Installation

Drop this repo into your vault's Claude Code skills directory:

git clone https://git.lissad.keenetic.name/Pikaliov/research-en.git \
    .claude/skills/research-en

Or as a submodule:

git submodule add https://git.lissad.keenetic.name/Pikaliov/research-en.git \
    .claude/skills/research-en

The five skills are auto-discovered on the next Claude Code session. Verify with /help — you should see /research, /research-add-items, /research-add-fields, /research-deep, /research-report.

Runtime dependency (for validate_json.py):

pip install pyyaml

research-deep calls validate_json.py via the ~/.claude/skills/research/validate_json.py path inside its prompt template — adjust if your install location differs.

File layout

research-en/
├── README.md                            — this file
├── research/
│   ├── SKILL.md                         — /research (preliminary)
│   └── validate_json.py                 — JSON ↔ fields.yaml coverage check (PyYAML)
├── research-add-items/SKILL.md          — /research-add-items
├── research-add-fields/SKILL.md         — /research-add-fields
├── research-deep/SKILL.md               — /research-deep (parallel, resumable)
└── research-report/SKILL.md             — /research-report (markdown synth)

Allowed tools per skill

Skill	Tools
research	Read, Write, Glob, WebSearch, Task, AskUserQuestion
research-add-items	Bash, Read, Write, Glob, WebSearch, Task, AskUserQuestion
research-add-fields	Bash, Read, Write, Glob, WebSearch, Task, AskUserQuestion
research-deep	Bash, Read, Write, Glob, WebSearch, Task
research-report	Read, Write, Glob, Bash, AskUserQuestion

Worked example

/research "AI Coding Assistants since 2024"
# → ./ai_coding_assistants/{outline.yaml, fields.yaml}

/research-add-items
# → adds Cursor, Windsurf, Aider, Continue, etc.

/research-deep
# → batch=4 agents, 2 items each → results/*.json
# → validate_json.py runs after each → coverage report

/research-report
# → ask: "Which fields in TOC besides name?" → github_stars, swe_bench_score
# → ./ai_coding_assistants/{generate_report.py, report.md}

Hard constraints (in skill prompts)

• All field values must be in English (deep phase).
• Mark uncertain values with [uncertain], list them in trailing uncertain array.
• Prompt templates inside research/SKILL.md and research-deep/SKILL.md are hard-reproduce: only {xxx} placeholders may be substituted, structure and wording must not be modified.
• Resume support: research-deep skips items that already have a JSON file in output_dir.
• Batch gating: research-deep waits for user approval between batches (interactive).