researchskills-extract

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

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.

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:

# 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.

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.

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.

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:

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.

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.)