researchskills-extract

Category: Research & Analysis | Uploader: ScienceIntelligence | Downloads: 0 | Version: v1.0（Latest）
Extract research skills from conversation history into ResearchSkills skill files.
Changelog: Source: GitHub https://github.com/ScienceIntelligence/ResearchSkills
Directory Structure

Current level: tree/main/researchskills-extract/commands/
📄 CONVERT-SKILL.md 8.5 KB
📄 researchskills-convert.md 8.1 KB
📄 researchskills-extract.md 11.8 KB
📄 SKILL.md 12.4 KB
SKILL.md

---
name: "researchskills-extract"
description: "Extract research skills from conversation history into ResearchSkills skill files."
---
# /researchskills-extract

Extract research skills from the user's Codex session history for **ResearchSkills**.

**Run automatically with THREE pauses for user consent:** once after classifying projects (Stage 2.5 — choose which projects to scan), once after scoring to offer local installation (Stage 6.5 — store skills in Claude/Codex), and once before upload (Stage 7 — choose whether to submit). Report progress at each milestone.

> **Prerequisite:** This skill spawns nested `codex exec` calls that need full network and filesystem access. Start Codex with: `codex -a never -s danger-full-access` (or `--dangerously-bypass-approvals-and-sandbox`). If the parent session is sandboxed, nested calls will fail with network errors.

You extract three types of cognitive memory from research conversations:
- **Procedural** — IF-THEN rules for **scientific research** decisions: methodology choices, data interpretation strategies, research direction pivots. NOT engineering workflows.
- **Semantic** — **Frontier scientific knowledge** the LLM doesn't have: domain-specific constraints, unpublished findings, corrections to scientific misconceptions. NOT tool/API behaviors.
- **Episodic** — **Research cognitive turning points**: hypothesis overturned, methodology abandoned for scientific reasons, unexpected findings that changed direction. NOT debugging episodes.

Everything else — discovery, formatting, validation, upload — is done by helper scripts. Do not reimplement their work.

---

## Pipeline

```
scan-sessions.js       ─┐
classify-projects.js   ─┤
extract-skills.js      ─┤  deterministic scripts (you call them)
  └─ codex exec         │  ← Codex exec call per session, inside the script
clean-skills.js        ─┤  ← review: reject/fix/merge
score-skills.js        ─┤  ← score: 3-dim value assessment
store-local.js         ─┤  ← optional: install skills into Claude/Codex
finalize.js            ─┘

You (main agent)       ← call scripts, read summaries, report
```

Helper scripts (installed at `~/.codex/skills/researchskills-extract/scripts/`):

| Script | What it does |
|--------|-------------|
| `scan-sessions.js` | Discover sessions, extract metadata, filter, group by project |
| `classify-projects.js` | Classify projects as research/engineering via Codex, pick domain/subdomain |
| `extract-skills.js` | **The core loop**: format each session → call `codex exec` → validate + cache skills |
| `validate-skills.js` | Validate skill markdown and cache to `~/.researchskills/cache/skills/` |
| `clean-skills.js` | Review extracted skills: reject engineering, fix PII, merge duplicates |
| `score-skills.js` | Score surviving skills on 3 dimensions: procedural, semantic, episodic value |
| `store-local.js` | Install extracted skills into user's local Claude/Codex config |
| `finalize.js` | Collect cached skills → upload to researchskills.ai |

---

## Arguments

- `--test` (alias: `test`): Test mode. Accept engineering sessions too (not just research). Tag all output as test data.
- No argument: Production mode. Only research sessions proceed.

Detect mode at start. Announce: `"Running in TEST MODE"` or `"Running in production mode"`.

---

## Stage 1 — Scan

```bash
mkdir -p ~/.researchskills/cache/meta ~/.researchskills/cache/skills
node ~/.codex/skills/researchskills-extract/scripts/scan-sessions.js
```

Reads `~/.researchskills/cache/work-list.json` output. Report: `"Found N sessions across M projects."`

---

## Stage 2 — Classify Projects

**YOU MUST call this script. Do NOT classify projects yourself.**

```bash
node ~/.codex/skills/researchskills-extract/scripts/classify-projects.js ~/.researchskills/cache/work-list.json --codex --verbose
```

For test mode, add `--test`.

The script calls Codex to classify each project as research/engineering and picks domain/subdomain from the taxonomy. It also filters out non-research sessions (e.g., researchskills-extract runs, build/deploy tasks) via `skip_patterns`.

Output: `~/.researchskills/cache/classification.json`.

Read the output file. For each project with `type: "research"`, use its `research_session_ids` (NOT `session_ids`), `domain`, `subdomain`, and `project_name` in later stages. Do NOT include skipped sessions.

The script generates an AI-summarized `project_name` for each project (e.g. "Protein Folding Simulation Pipeline") instead of using the raw folder name. Use this `project_name` in Stage 6 finalize. If `project_name` is null, fall back to the `slug`.

Report: `"Classified N projects. Proceeding with M."`

---

## Stage 2.5 — Project Consent Gate

**PAUSE and ask the user.** After classification, show all discovered projects and let the user choose which to scan.

Read `~/.researchskills/cache/classification.json` and display:

```
Select which projects to scan for research skills (all research projects selected — deselect any project that is not related to research):

  [x] 1. Protein Folding Pipeline     (4 sessions, research, quantitative-biology)
  [x] 2. Quantum Monte Carlo Study    (3 sessions, research, physics)
  [ ] 3. Personal Website             (3 sessions, engineering)
  [x] 4. Dotfiles                     (2 sessions, other)

Enter numbers to toggle, or press Enter to continue:
```

All projects are pre-selected by default. Users can deselect individual projects by number.

**YOU MUST STOP HERE AND WAIT FOR THE USER TO RESPOND.** Use `ask` (Codex) or `AskUserQuestion` (Claude Code) to present the project list and block until the user replies. Do NOT continue to Stage 3 without an explicit user response. If no interactive tool is available, print the list and end your turn — the user's next message is their selection.

Only pass user-approved projects to Stage 3+. Remove deselected project session IDs from all subsequent `--session-ids` arguments.

Report: `"Proceeding with N projects (M sessions) after user confirmation."`

---

## Stage 3 — Extract Skills Per Session

### MANDATORY: Use --single-batch and loop. NEVER run all at once.

The extraction script MUST be called in a loop with `--single-batch`. Each call processes ONE batch (~5 parallel Codex calls) then exits. You call it again in a new tool call. This keeps the user informed of progress and prevents the UI from freezing.

**FORBIDDEN patterns (will cause long freezes):**
- `run_in_background: true` — user sees nothing for 10+ minutes
- Omitting `--single-batch` — script runs all batches internally, no progress visible

**REQUIRED pattern:**

```bash
# REPEAT this exact call in a loop. Each call = 1 batch.
node ~/.codex/skills/researchskills-extract/scripts/extract-skills.js ~/.researchskills/cache/work-list.json \
  --codex \
  --domain <domain> \
  --subdomain <subdomain> \
  --contributor "$(git config user.name)" \
  --session-ids <ALL-research-session-ids-csv> \
  --single-batch \
  --verbose
```

**Loop logic:**
1. Run the command above (foreground, NOT background)
2. Read the output. Report to user: "Batch N/M done: X skills extracted, Y calls remaining"
3. If output says `0 Codex calls remaining` or `All sessions already cached` → **stop, go to Stage 4**
4. Otherwise → run the **same command again** (it auto-skips cached segments)

Pass ALL research session IDs from Stage 2. Do NOT drop sessions or pick a subset.

If you need to process multiple projects with different domains, call the script once per project with `--session-ids` filtering to that project's sessions.

---

## Stage 4 — Clean Skills

Run review of all extracted skills: reject engineering content, fix PII leaks, merge duplicates.

```bash
node ~/.codex/skills/researchskills-extract/scripts/clean-skills.js \
  --codex \
  --session-ids <ALL-research-session-ids-csv> \
  --verbose
```

This spawns a Codex instance that directly reads, deletes, and edits skill files on disk.

Report: `"Clean: kept N, rejected M, merged K."`

---

## Stage 5 — Score Skills

Run assessment of the value of each surviving skill on 3 dimensions.

```bash
node ~/.codex/skills/researchskills-extract/scripts/score-skills.js \
  --codex \
  --session-ids <ALL-research-session-ids-csv> \
  --verbose
```

This spawns a Codex instance that reads each skill and writes `review_scores` (procedural, semantic, episodic — each 0-5) into the YAML frontmatter.

Report: `"Scored N skills. Avg: procedural X.X, semantic X.X, episodic X.X."`

---

## Stage 6 — Finalize Per Project (collect only, no upload yet)

Use the AI-generated `project_name` from classification.json (Stage 2). Do NOT use the raw folder name.

**Do NOT pass `--upload` here.** Collect skills locally first. Upload requires explicit user consent in Stage 7.

```bash
node ~/.codex/skills/researchskills-extract/scripts/finalize.js \
  --session-ids <ALL-research-session-ids-csv> \
  --domain <domain> \
  --subdomain <subdomain> \
  --contributor "$(git config user.name)" \
  --project-name "<project_name from classification>" \
  --project-slug "<slug>"
```

---

## Stage 6.5 — Store Skills Locally (Optional)

**Third consent gate.** After finalize collects skills, ask the user whether to install them into their local AI coding tool so the skills are available as context in future sessions.

Use `ask` (Codex) or `AskUserQuestion` (Claude Code) to present the options. If no interactive tool is available, print the options and end your turn — the user's next message is their selection.

- Question: "Install extracted skills into your local AI coding tool?"
- Option A: "Yes, install to Claude Code" — stores skills to `~/.claude/commands/researchskills/<slug>.md`
- Option B: "Yes, install to Codex" — stores skills to `~/.codex/skills/researchskills-<slug>/SKILL.md`
- Option C: "Yes, install to both"
- Option D: "No, skip local install"

**YOU MUST STOP HERE AND WAIT FOR THE USER TO RESPOND.** Do NOT continue to Stage 7 without an explicit user response.

If the user picks A, B, or C, run:

```bash
node ~/.codex/skills/researchskills-extract/scripts/store-local.js \
  --target <claude|codex|both> \
  --session-ids <ALL-research-session-ids-csv>
```

Report: `"Installed N skills to <target>. M already up-to-date."`

If the user picks D, skip and continue to Stage 7.

---

## Stage 7 — Consent and Upload

**Fourth consent gate.** Pause and ask the user before uploading anything.

Show the user what was extracted:

```
═══════════════════════════════════════════════════════
  /researchskills-extract — Extraction Complete!
═══════════════════════════════════════════════════════

Extracted N skills from M sessions across P projects:
  • Episodic:   E skills
  • Semantic:   S skills
  • Procedural: Pr skills

Review:
  • Kept: K / Rejected: R / Merged: G
  • Avg scores: procedural X.X, semantic X.X, episodic X.X

⚠ Nothing has been uploaded yet. Your skills are saved
  locally. Would you like to submit them to ResearchSkills
  for reviewer review?

  Skills will be stored on researchskills.ai and reviewed
  by a maintainer before publication (CC-BY 4.0).
═══════════════════════════════════════════════════════
```

Ask for explicit consent:
- "Yes, submit for review" — re-run finalize with `--upload`
- "No, keep local only" — skip upload, tell user where files are saved

If the user consents, re-run finalize with `--upload`.

**Headless/SSH detection:** If running over SSH (SSH_CONNECTION or SSH_CLIENT env vars set) or on a headless Linux server (no DISPLAY), the upload script automatically detects this and:
- Disables browser opening
- Prints the review URL for the user to visit from any browser

When the user has consented via the prompt above, pass `--consent` to include `consent: true` in the upload payload.

```bash
node ~/.codex/skills/researchskills-extract/scripts/finalize.js \
  --session-ids <ALL-research-session-ids-csv> \
  --domain <domain> \
  --subdomain <subdomain> \
  --contributor "$(git config user.name)" \
  --project-name "<project_name from classification>" \
  --project-slug "<slug>" \
  --upload
```

Then show:
```
Review your skills:
  → https://researchskills.ai/review/batch/<batchId>
```

If headless, also show:
```
  (Sign in with GitHub on the review page to claim credit and submit.)
```
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
researchskills-extract

Directory Structure

SKILL.md

Report

Notice
