Initial commit — research-en skill bundle
5-skill bundle for structured, resumable, parallel deep research: - /research — preliminary outline + fields generation - /research-add-items — supplement research objects - /research-add-fields — supplement field definitions - /research-deep — parallel agents per item, resumable, JSON-validated - /research-report — JSON to markdown report with TOC Includes validate_json.py for fields.yaml coverage check (PyYAML required). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
159
README.md
Normal file
159
README.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# 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|moderate|detailed`). |
|
||||
| `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`
|
||||
```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`
|
||||
```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`
|
||||
```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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
git clone https://git.lissad.keenetic.name/Pikaliov/research-en.git \
|
||||
.claude/skills/research-en
|
||||
```
|
||||
|
||||
Or as a submodule:
|
||||
|
||||
```bash
|
||||
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`):
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```text
|
||||
/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).
|
||||
Reference in New Issue
Block a user