chore: migrate skills to agents layout

skills/_template-episodic.md → .agents/skills/_template-episodic.md

@@ -3,7 +3,7 @@ name: your-skill-name
 memory_type: episodic
 subtype: failure                               # failure | adaptation | anomalous
 domain: physics                                # physics | mathematics | computer-science | quantitative-biology | statistics | eess | economics | quantitative-finance
-subdomain: geophysics                          # arXiv-aligned subdomain (see skills/<domain>/ for options)
+subdomain: geophysics                          # arXiv-aligned subdomain (see .agents/skills/<domain>/ for options)
 contributor: your-github-username
 ---
 
@@ -19,8 +19,8 @@ contributor: your-github-username
     anomalous  — Expected A, observed B — turned out important
 
   File placement:
-    skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md
-    Example: skills/physics/geophysics/jdoe/episodic/failure--gradient-explosion-under-fp16.md
+    .agents/skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md
+    Example: .agents/skills/physics/geophysics/jdoe/episodic/failure--gradient-explosion-under-fp16.md
 
   Instructions:
     1. Fill in all frontmatter fields above.

skills/_template-procedural.md → .agents/skills/_template-procedural.md

@@ -3,7 +3,7 @@ name: your-skill-name
 memory_type: procedural
 subtype: tie                                   # tie | no-change | constraint-failure | operator-fail
 domain: physics                                # physics | mathematics | computer-science | quantitative-biology | statistics | eess | economics | quantitative-finance
-subdomain: geophysics                          # arXiv-aligned subdomain (see skills/<domain>/ for options)
+subdomain: geophysics                          # arXiv-aligned subdomain (see .agents/skills/<domain>/ for options)
 contributor: your-github-username
 ---
 
@@ -20,8 +20,8 @@ contributor: your-github-username
     operator-fail    — Correct approach selected but execution fails
 
   File placement:
-    skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md
-    Example: skills/physics/geophysics/jdoe/procedural/tie--exploiting-cross-domain-concepts.md
+    .agents/skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md
+    Example: .agents/skills/physics/geophysics/jdoe/procedural/tie--exploiting-cross-domain-concepts.md
 
   Instructions:
     1. Fill in all frontmatter fields above.

skills/_template-semantic.md → .agents/skills/_template-semantic.md

@@ -3,7 +3,7 @@ name: your-skill-name
 memory_type: semantic
 subtype: correction                            # frontier | non-public | correction
 domain: physics                                # physics | mathematics | computer-science | quantitative-biology | statistics | eess | economics | quantitative-finance
-subdomain: geophysics                          # arXiv-aligned subdomain (see skills/<domain>/ for options)
+subdomain: geophysics                          # arXiv-aligned subdomain (see .agents/skills/<domain>/ for options)
 contributor: your-github-username
 ---
 
@@ -19,8 +19,8 @@ contributor: your-github-username
     correction  — LLM actively gets this wrong — confident but incorrect default belief
 
   File placement:
-    skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md
-    Example: skills/physics/geophysics/jdoe/semantic/correction--lsm-grid-resolution-is-a-design-choice.md
+    .agents/skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md
+    Example: .agents/skills/physics/geophysics/jdoe/semantic/correction--lsm-grid-resolution-is-a-design-choice.md
 
   Instructions:
     1. Fill in all frontmatter fields above.

skills/_template.md → .agents/skills/_template.md

@@ -16,10 +16,10 @@ status: draft                                # leave as draft; reviewer will upd
   1. Delete these comment blocks before submitting.
   2. Fill in ALL required frontmatter fields above.
   3. Complete each section below. "Required" sections must be present.
-  4. Run `python utils/tools/validate.py skills/<domain>/<subdomain>/<your-skill>.md` before opening a PR.
+  4. Run `python utils/tools/validate.py .agents/skills/<domain>/<subdomain>/<your-skill>.md` before opening a PR.
   5. See utils/SKILL_SCHEMA.md for full field documentation.
 
-  NOTE: The primary contribution method is now skills via /researchskills-extract.
+  NOTE: The primary contribution method is now the ResearchSkills meta skill.
   This template is for manually written skills only.
 -->
 

.agents/skills/researchskills-extract/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: researchskills-extract
+description: Extract or convert existing research know-how into ResearchSkills files under .agents/skills/.
+---
+
+## When
+Use this meta skill when the task is to create ResearchSkills from existing material rather than to apply a domain skill directly. Typical inputs include AI conversation history, local agent skills, memory files, rubrics, prompts, lab notes, research logs, or project instructions that may contain reusable research know-how.
+
+Do not use it for generic engineering, DevOps, UI, database, Docker, package-manager, git, or textbook material unless the content directly changes how research should be done.
+
+## Decision
+Treat extraction and conversion as a normal ResearchSkills skill workflow, not as a separate npm package or special command.
+
+Preferred:
+- Ask for the source path, conversation export, or pasted source material.
+- Use `scripts/researchskills-extract.sh` on macOS/Linux or `scripts/researchskills-extract.ps1` on Windows when the source is a file or directory. The helper builds a bounded source bundle, a manifest, and an extraction prompt without installing anything globally.
+- Read only the requested source bundle and directly referenced files needed to understand it.
+- Extract one reusable research know-how item per output skill.
+- Assign exactly one memory type: `procedural`, `semantic`, or `episodic`.
+- Assign exactly one subtype:
+  - `procedural`: `tie`, `no-change`, `constraint-failure`, `operator-fail`
+  - `semantic`: `frontier`, `non-public`, `correction`
+  - `episodic`: `failure`, `adaptation`, `anomalous`
+- Place the generated file under `.agents/skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md`.
+- Remove private paths, usernames, private URLs, project names, and collaborator names while preserving scientific parameters, methods, model names, datasets, and mechanisms.
+- Validate the generated files, then submit them by GitHub PR.
+
+Helper examples:
+
+```bash
+.agents/skills/researchskills-extract/scripts/researchskills-extract.sh path/to/source \
+  --domain computer-science \
+  --subdomain artificial-intelligence \
+  --contributor your-github-handle
+```
+
+```powershell
+.agents/skills/researchskills-extract/scripts/researchskills-extract.ps1 path\to\source `
+  -Domain computer-science `
+  -Subdomain artificial-intelligence `
+  -Contributor your-github-handle
+```
+
+After running the helper, read the generated `extraction-prompt.md`, create skill files under `.agents/skills/`, and validate them with:
+
+```bash
+python utils/tools/validate.py .agents/skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md
+```
+
+Rejected:
+- Do not install or document a separate npm package for this workflow.
+- Do not preserve legacy slash-command framing when a normal skill invocation is enough.
+- Do not merge multiple unrelated insights into one broad skill.
+- Do not create skills that only restate common LLM knowledge.
+
+Reasoning: the extraction workflow is itself a meta skill: it teaches an agent how to transform local knowledge into ResearchSkills. Keeping it in `.agents/skills/` makes installation, review, and contribution follow the same path as the rest of the library.
+
+## Local Verifiers
+- Every generated skill has frontmatter fields: `name`, `memory_type`, `subtype`, `domain`, `subdomain`, and `contributor`.
+- The file path matches its frontmatter memory type and subtype.
+- The helper output includes `source-manifest.tsv`, `source-bundle.md`, and `extraction-prompt.md`.
+- The body contains a concrete trigger, action or fact, reasoning mechanism, and failure or anti-example guidance when applicable.
+- Private identifiers are removed, but scientific content remains specific enough to be useful.
+- Repository validation passes for the generated skill files.
+
+## Failure Handling
+If the source material is too broad, ask for a narrower source directory, date range, topic, or conversation export before extracting. If the content is mostly generic engineering, report that no ResearchSkills-quality item was found and list the closest rejected candidates. If domain or subdomain is unclear, choose the closest arXiv-aligned folder and mention the uncertainty in the PR.
+
+## Anti-exemplars
+- A build failure fixed by changing an npm version is not a ResearchSkill unless it reveals a research-method constraint.
+- A prompt template for routine code review is not a ResearchSkill unless it encodes domain-specific research judgment.
+- A lab-specific secret, private endpoint, or personal workflow should be de-identified or skipped.

.agents/skills/researchskills-extract/scripts/researchskills-extract.ps1

@@ -0,0 +1,193 @@
+param(
+  [Parameter(Position = 0)]
+  [string]$Source,
+
+  [string]$Out,
+  [string]$Domain = "computer-science",
+  [string]$Subdomain = "artificial-intelligence",
+  [string]$Contributor = $env:USERNAME,
+  [int]$MaxBytes = 200000,
+  [string]$ValidateDir,
+  [switch]$Help
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Show-Usage {
+  @"
+Usage:
+  .\researchskills-extract.ps1 <source-file-or-dir> [options]
+
+Options:
+  -Out <dir>             Output directory for bundle/prompt.
+  -Domain <slug>         Target ResearchSkills domain.
+  -Subdomain <slug>      Target ResearchSkills subdomain.
+  -Contributor <handle>  Public contributor handle.
+  -MaxBytes <n>          Max bytes copied into source-bundle.md. Default: 200000.
+  -ValidateDir <dir>     Validate existing generated .md files under this repo path.
+  -Help                  Show this help.
+
+This helper does not call an LLM and does not install commands. It prepares a
+bounded source bundle and a high-signal extraction prompt for the agent.
+"@
+}
+
+if ($Help) {
+  Show-Usage
+  exit 0
+}
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$RepoRoot = Resolve-Path (Join-Path $ScriptDir "../../../..")
+$Validator = Join-Path $RepoRoot "utils/tools/validate.py"
+
+if ($ValidateDir) {
+  if (-not (Test-Path $Validator)) {
+    throw "validator not found: $Validator"
+  }
+  $files = Get-ChildItem -Path $ValidateDir -Recurse -File -Filter "*.md" | ForEach-Object { $_.FullName }
+  if (-not $files -or $files.Count -eq 0) {
+    throw "no markdown files found under $ValidateDir"
+  }
+  & python $Validator @files
+}
+
+if (-not $Source) {
+  Show-Usage
+  exit 2
+}
+if (-not (Test-Path $Source)) {
+  throw "source not found: $Source"
+}
+if (-not $Contributor) {
+  $Contributor = "anonymous"
+}
+
+if (-not $Out) {
+  $stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+  $Out = Join-Path $RepoRoot ".researchskills-extract/$stamp"
+}
+New-Item -ItemType Directory -Force -Path $Out | Out-Null
+
+$Manifest = Join-Path $Out "source-manifest.tsv"
+$Bundle = Join-Path $Out "source-bundle.md"
+$Prompt = Join-Path $Out "extraction-prompt.md"
+
+"path`tbytes" | Set-Content -Path $Manifest -Encoding utf8
+@"
+# ResearchSkills Source Bundle
+
+Source: $Source
+Generated: $((Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ"))
+Byte limit: $MaxBytes
+
+"@ | Set-Content -Path $Bundle -Encoding utf8
+
+function Test-TextCandidate([string]$Path) {
+  $ext = [IO.Path]::GetExtension($Path).ToLowerInvariant()
+  return @(".md", ".markdown", ".txt", ".json", ".jsonl", ".yaml", ".yml", ".csv", ".tsv", ".log").Contains($ext)
+}
+
+function Append-SourceFile([string]$Path) {
+  if (-not (Test-Path $Path -PathType Leaf)) { return }
+  if (-not (Test-TextCandidate $Path)) { return }
+
+  $size = (Get-Item $Path).Length
+  $current = (Get-Item $Bundle).Length
+  if (($current + $size) -gt $MaxBytes) {
+    "$Path`t$size`tSKIPPED_LIMIT" | Add-Content -Path $Manifest -Encoding utf8
+    return
+  }
+
+  "$Path`t$size" | Add-Content -Path $Manifest -Encoding utf8
+  $text = Get-Content -Raw -Path $Path
+  $text = $text -replace "```", "` ` `"
+  @"
+
+
+## File: $Path
+
+``````text
+$text
+``````
+"@ | Add-Content -Path $Bundle -Encoding utf8
+}
+
+if (Test-Path $Source -PathType Leaf) {
+  Append-SourceFile (Resolve-Path $Source)
+} else {
+  $skipDirs = @(".git", "node_modules", ".venv", "venv", "dist", "build", "__pycache__", ".researchskills-extract")
+  Get-ChildItem -Path $Source -Recurse -File |
+    Where-Object {
+      $parts = $_.FullName -split [regex]::Escape([IO.Path]::DirectorySeparatorChar)
+      -not ($parts | Where-Object { $skipDirs -contains $_ })
+    } |
+    Sort-Object FullName |
+    ForEach-Object { Append-SourceFile $_.FullName }
+}
+
+$bundleText = Get-Content -Raw -Path $Bundle
+@"
+# ResearchSkills Extraction Prompt
+
+Use the ResearchSkills meta skill to extract reusable research know-how from
+the source bundle below. Write output files directly under:
+
+``.agents/skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md``
+
+Default metadata:
+
+- domain: ``$Domain``
+- subdomain: ``$Subdomain``
+- contributor: ``$Contributor``
+
+Quality gate:
+
+1. Extract only research know-how: scientific methodology, domain facts,
+   computational science methods, research design, evaluation strategy, or
+   concrete scientific episodes.
+2. Reject pure engineering, package-manager, git, auth, deployment, UI, or
+   generic coding lessons unless they directly constrain the research method.
+3. One skill file equals one reusable insight.
+4. De-identify private paths, usernames, project names, private URLs, and
+   collaborator names. Preserve scientific methods, model names, datasets,
+   parameters, and mechanisms.
+5. Prefer 0 high-quality skills over broad low-value skills.
+
+Memory types:
+
+- procedural: ``tie``, ``no-change``, ``constraint-failure``, ``operator-fail``
+- semantic: ``frontier``, ``non-public``, ``correction``
+- episodic: ``failure``, ``adaptation``, ``anomalous``
+
+Validation:
+
+``````bash
+python utils/tools/validate.py .agents/skills/<domain>/<subdomain>/<contributor>/<memory_type>/<subtype>--<skill-name>.md
+``````
+
+After extraction, summarize:
+
+- files created
+- candidates rejected and why
+- validation command/result
+
+---
+
+$bundleText
+"@ | Set-Content -Path $Prompt -Encoding utf8
+
+@"
+ResearchSkills extraction helper complete.
+
+Output directory: $Out
+Manifest:         $Manifest
+Source bundle:    $Bundle
+Prompt:           $Prompt
+
+Next:
+  1. Read $Prompt.
+  2. Create ResearchSkills files under .agents/skills/.
+  3. Validate with: python utils/tools/validate.py <generated-skill.md>
+"@