@brainpilot/skills 0.0.6

package/skills/01_Meta-Skills/repo-to-skill/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: "repo-to-skill"
+description: "Convert a GitHub repository or local codebase into a well-structured Claude Code skill with progressive disclosure. Use this skill whenever the user provides a GitHub URL or local repo path and asks to turn it into a skill, create a skill from a repo, or convert a library/tool/framework into reusable skill documentation. Also trigger when users say things like 'make a skill from this repo', 'turn this codebase into a skill', or 'I want a skill for [library name]'."
+version: "1.0.0"
+authors:
+  - "Claude (AI-assisted)"
+review_status: "ai-generated"
+---
+
+# Repo-to-Skill: Convert a Repository into a Claude Code Skill
+
+## Purpose
+
+This skill encodes the complete workflow for transforming a GitHub repository (or local codebase) into a well-structured Claude Code skill. It guides you through cloning, exploring, extracting key information, and assembling a skill with proper progressive disclosure — a concise SKILL.md entry point backed by detailed reference files.
+
+## When to Use
+
+Activate when the user:
+- Provides a GitHub URL and asks to create a skill from it
+- Points to a local repository path and wants it converted to a skill
+- Says "make a skill from this repo/library/tool"
+- Wants to document a codebase as a reusable skill
+
+## Workflow Overview
+
+```
+1. Acquire repo  →  2. Explore broadly  →  3. Collect key info  →  4. Design structure  →  5. Write SKILL.md + references
+```
+
+---
+
+## Phase 1: Acquire the Repository
+
+### From GitHub URL
+```bash
+# Clone to a working directory
+git clone <github-url> /tmp/skill-source-repo
+# or clone to a user-specified path
+```
+
+If the user provides just a repo name (e.g., "mne-tools/mne-python"), construct the URL:
+```bash
+git clone https://github.com/<owner>/<repo>.git /tmp/skill-source-repo
+```
+
+### From Local Path
+If the user provides a local path (e.g., `/srv/repos/my-library`), use it directly. Verify it exists before proceeding.
+
+### Already Available
+Check if the repo is already cloned locally before downloading again.
+
+---
+
+## Phase 2: Explore the Repository
+
+This is the most important phase. Explore broadly and deeply — the quality of the skill depends on how well you understand the repo. Use parallel subagents when possible to speed up exploration.
+
+### 2.1 Top-Level Orientation
+
+Read these files first (if they exist):
+- `README.md` / `README.rst` — project overview, installation, quick start
+- `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.md` — recent API changes
+- `pyproject.toml` / `setup.py` / `setup.cfg` / `package.json` — dependencies, version
+- `CONTRIBUTING.md` — project conventions
+- `LICENSE` — license type
+
+Then list the top-level directory structure to understand the project layout.
+
+### 2.2 Core Source Code
+
+Identify the main source directory (often `src/`, `lib/`, or the package name itself). Then:
+
+1. Read `__init__.py` (or equivalent entry point) to find all exported modules/classes/functions
+2. List all submodules/subdirectories
+3. For each major submodule, read its `__init__.py` to get the public API
+4. Read key implementation files for important classes/functions — focus on docstrings and signatures, not internal logic
+
+### 2.3 Documentation
+
+Look for documentation in these common locations:
+- `docs/` or `doc/` directory
+- `examples/` directory — working code examples are gold
+- `tutorials/` directory — step-by-step guides
+- API reference docs (often generated, but source `.rst` or `.md` files are useful)
+- Jupyter notebooks (`.ipynb`) in any directory
+
+### 2.4 Examples and Tutorials
+
+These are the most valuable resources for a skill. For each example/tutorial:
+- Note what it demonstrates
+- Extract the key code patterns
+- Identify the recommended parameter values and best practices
+
+### 2.5 Tests (Optional)
+
+Skim test files to discover edge cases, expected behaviors, and usage patterns that aren't in the docs.
+
+### Exploration Strategy
+
+Use the Agent tool with `subagent_type=Explore` for broad exploration, or launch multiple parallel subagents to cover different areas simultaneously:
+
+```
+Agent 1: Explore top-level structure + README + core __init__.py files
+Agent 2: Explore tutorials/ and examples/ directories, read representative files
+Agent 3: Explore docs/ for API reference, read key module documentation
+```
+
+The goal is to collect:
+- Complete list of public API (classes, functions, constants)
+- Recommended usage patterns and pipelines
+- Parameter defaults and recommended values
+- Common pitfalls and gotchas
+- Code examples for each major feature
+
+---
+
+## Phase 3: Design the Skill Structure
+
+### Determine Scope
+
+Based on exploration, decide:
+- What is the skill's primary purpose? (e.g., "guide users through X analysis pipeline")
+- What are the major topic areas? (these become reference files)
+- What belongs in the main SKILL.md vs. references?
+
+### Progressive Disclosure Architecture
+
+```
+skill-name/
+├── SKILL.md              (< 500 lines — overview, pipeline, quick reference)
+└── references/
+    ├── topic-a.md        (detailed API + examples for topic A)
+    ├── topic-b.md        (detailed API + examples for topic B)
+    ├── topic-c.md        (detailed API + examples for topic C)
+    └── ...
+```
+
+Rules of thumb:
+- SKILL.md: Pipeline overview, core concepts, quick-start code, common pitfalls, reference table pointing to detail files
+- Each reference file: One major topic, complete API listing, detailed code examples, parameter tables
+- Keep each file under 300 lines for readability; split if larger
+- Include a "Reference Files" table in SKILL.md so the model knows when to read each file
+
+### Reuse Repo Resources Directly
+
+When the repo already has well-written documentation, examples, or reference material, copy them directly into `references/` rather than rewriting. This saves effort and preserves accuracy:
+
+```bash
+# Copy useful docs directly
+cp /tmp/skill-source-repo/docs/api_reference.md references/
+cp /tmp/skill-source-repo/examples/quickstart.py references/
+cp /tmp/skill-source-repo/tutorials/getting_started.md references/
+```
+
+Rename files to be descriptive if needed. Add a brief header noting the source.
+
+---
+
+## Phase 4: Write the SKILL.md
+
+### Naming Rule
+
+Skill name may only contain lowercase letters, numbers, and hyphens. The name must match the folder name. For example, a skill in folder `my-cool-tool/` must have `name: "my-cool-tool"` in its frontmatter.
+
+### Required Structure
+
+```markdown
+---
+name: "my-skill-name"
+description: "One-line description of what this skill provides"
+version: "1.0.0"
+authors:
+  - "Claude (AI-assisted)"
+review_status: "ai-generated"
+---
+
+# Skill Title
+
+## Purpose
+What domain knowledge this skill encodes and why it's useful.
+
+## When to Use This Skill
+Trigger conditions — what user phrases/contexts activate this skill.
+
+## Reference Files (Progressive Disclosure)
+| Topic | File | When to Read |
+|-------|------|--------------|
+| Topic A | `references/topic-a.md` | User asks about A |
+| Topic B | `references/topic-b.md` | User asks about B |
+
+## Overview / Pipeline
+High-level workflow or concept map.
+
+## Quick Start
+Minimal working example covering the most common use case.
+
+## Key Concepts
+Core data structures, important classes, essential functions.
+
+## Common Pitfalls
+Numbered list of mistakes to avoid, with brief explanations.
+
+## [Additional sections as needed]
+```
+
+### Writing Guidelines
+
+1. Lead with the pipeline/workflow — users want to know "what do I do first?"
+2. Include runnable code examples — not pseudocode
+3. Cite parameter values with sources when possible
+4. Keep SKILL.md under 500 lines — move details to references
+5. Use tables for API listings and parameter comparisons
+6. The reference table is critical — it tells the model when to load each file
+
+---
+
+## Phase 5: Write Reference Files
+
+For each major topic area, create a reference file:
+
+```markdown
+# Topic Name Reference
+
+## Table of Contents
+1. [Section 1](#section-1)
+2. [Section 2](#section-2)
+...
+
+## Section 1
+[Detailed API, parameters, code examples]
+
+## Section 2
+[More details]
+```
+
+### What to Include in References
+
+- Complete function/class signatures with all parameters
+- Parameter tables with types, defaults, and descriptions
+- Multiple code examples showing different use cases
+- Tips for parameter selection
+- Links between related functions
+
+### Reusing Repo Content
+
+Prefer copying existing high-quality content from the repo:
+- Tutorial code → reference examples
+- API docstrings → function reference tables
+- README sections → overview content
+- Example scripts → working code snippets
+
+Only rewrite when the original content is poorly organized, outdated, or too verbose.
+
+---
+
+## Quality Checklist
+
+Before finishing, verify:
+
+- [ ] Skill name contains only lowercase letters, numbers, and hyphens, and matches the folder name
+- [ ] SKILL.md is under 500 lines
+- [ ] All major features/modules are covered
+- [ ] Reference table in SKILL.md lists all reference files with "when to read" guidance
+- [ ] Each reference file has a table of contents
+- [ ] Code examples are complete and runnable
+- [ ] Common pitfalls section exists
+- [ ] Quick start example covers the most common use case
+- [ ] No reference file exceeds ~300 lines (split if needed)
+- [ ] Skill directory uses kebab-case naming
+
+---
+
+## Example: Converting a Python Library
+
+For a Python library like `pandas`:
+
+```
+pandas-guide/
+├── SKILL.md                    # Overview, core objects (DataFrame, Series), quick start
+└── references/
+    ├── io.md                   # read_csv, read_excel, to_parquet, etc.
+    ├── selection-indexing.md    # loc, iloc, boolean indexing, query
+    ├── groupby-aggregation.md  # groupby, agg, transform, pivot_table
+    ├── merging-joining.md      # merge, join, concat
+    ├── time-series.md          # DatetimeIndex, resample, rolling
+    └── visualization.md        # plot(), plot.bar(), etc.
+```
+
+The SKILL.md would contain the DataFrame/Series overview, a quick-start example, and a reference table pointing to each topic file.

package/skills/01_Meta-Skills/share-case/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: "share-case"
+description: "One-command community case sharing — capture research context from your session and submit to GitHub Discussions"
+domain: "meta-skill"
+version: "1.0.0"
+review_status: "ai-generated"
+---
+
+# Share Case
+
+## Purpose
+
+This meta-skill captures a researcher's experience using any skill in this repository and submits it as a structured case to GitHub Discussions. It handles all formatting and submission so users never need to leave their terminal or know Git.
+
+## When to Use This Skill
+
+Activate when the user:
+
+- Says "share this case", "share my experience", "分享这个案例"
+- Wants to document how they used a skill in their research
+- Asks how to contribute a usage example
+
+---
+
+## Research Planning Protocol
+
+Before starting the case sharing process, you MUST:
+
+1. **Identify the skill used** — Which skill(s) from this repository were used in the current session?
+2. **Clarify sharing scope** — What aspects of the experience does the user want to share?
+3. **Declare what will be extracted** — List the specific conversation elements that will be included
+4. **Note privacy considerations** — Are there dataset names, lab identifiers, or participant details that should be anonymized?
+5. **Present the extraction plan to the user and WAIT for confirmation** before proceeding.
+
+For detailed methodology guidance, see `skills/research-literacy/SKILL.md`.
+
+## ⚠️ Verification Notice
+
+This skill was generated by AI from academic literature. All parameters, thresholds, and citations require independent verification before use in research. If you find errors, please [open an issue](https://github.com/HaoxuanLiTHUAI/awesome_cognitive_and_neuroscience_skills/issues).
+
+---
+
+## Prerequisites
+
+This skill supports two submission methods:
+
+1. **Direct submission via `gh` CLI** (Recommended)
+   - Requires `gh` CLI installed and authenticated
+   - Run `gh auth status` to check
+   - Install from https://cli.github.com/ and run `gh auth login`
+
+2. **Manual submission via web browser**
+   - No `gh` CLI required
+   - Opens GitHub Discussions page in browser
+   - User copies and pastes the generated case
+
+The skill will check for `gh` availability and let the user choose their preferred method.
+
+**GitHub Discussions** must be enabled on the repository. The skill submits to the "Show & Tell" category.
+
+---
+
+## Interactive Flow
+
+### Step 1 — Quick Survey
+
+Present these questions using multiple-choice format:
+
+**Q1: Which skill did you use?**
+- Auto-detect from the current session context (list skills that were activated)
+- Let the user confirm or select manually from the full skill list
+
+**Q2: What was your research scenario?**
+- Formal experiment
+- Coursework or teaching
+- Method exploration
+- Paper reproduction
+- Other (free text)
+
+**Q3: How helpful was the skill? (1-5)**
+- 1 = Not helpful
+- 2 = Slightly helpful
+- 3 = Moderately helpful
+- 4 = Very helpful
+- 5 = Extremely helpful
+
+**Q4: What was most valuable? (select all that apply)**
+- Correct methodology guidance
+- Validated parameters and thresholds
+- Pitfall warnings
+- Complete pipeline coverage
+- Literature references
+- Other (free text)
+
+### Step 2 — Context Extraction
+
+Extract the following from the current conversation:
+
+1. **Research context** — The user's original research question and experimental setup
+2. **Key recommendations** — The main suggestions the skill provided (parameters, methods, warnings)
+3. **Follow-up adjustments** — Any modifications made during the conversation
+4. **Outcome summary** — What the user ultimately decided to do
+
+Format each as a concise paragraph. Do NOT include raw conversation transcripts — synthesize into readable summaries.
+
+### Step 3 — User Review and Submission Choice
+
+Display the complete case preview using the format below.
+
+**First, check `gh` CLI availability:**
+
+```bash
+gh auth status 2>&1
+```
+
+**Then present submission options using AskUserQuestion:**
+
+If `gh` is available:
+- **Submit via gh CLI (Recommended)** — Direct submission to GitHub Discussions
+- **Open in browser** — Manual submission via web interface
+- **Delete sections** — Remove specific paragraphs before submitting
+- **Anonymize** — Replace specific names (datasets, labs, participants)
+- **Abort** — Cancel without submitting
+
+If `gh` is NOT available:
+- **Open in browser** — Manual submission via web interface
+- **Delete sections** — Remove specific paragraphs before submitting
+- **Anonymize** — Replace specific names (datasets, labs, participants)
+- **Abort** — Cancel without submitting
+
+**You MUST wait for explicit user confirmation before proceeding to Step 4.**
+
+### Step 4 — Submit to GitHub
+
+Based on the user's choice in Step 3:
+
+#### Option A: Submit via `gh` CLI
+
+Create a GitHub Discussion in the "Show & Tell" category.
+
+**First, get repository and category IDs:**
+
+```bash
+gh api graphql -f query='
+{
+  repository(owner: "HaoxuanLiTHUAI", name: "awesome_cognitive_and_neuroscience_skills") {
+    id
+    discussionCategories(first: 10) {
+      nodes {
+        id
+        name
+      }
+    }
+  }
+}'
+```
+
+**Then create the discussion:**
+
+```bash
+gh api graphql -f query='
+mutation {
+  createDiscussion(input: {
+    repositoryId: "REPO_ID",
+    categoryId: "SHOW_AND_TELL_CATEGORY_ID",
+    title: "Community Case: SKILL_NAME",
+    body: "CASE_BODY_HERE"
+  }) {
+    discussion {
+      url
+    }
+  }
+}'
+```
+
+On success, display the Discussion URL:
+```
+✅ Case shared successfully!
+🔗 Discussion URL: [URL]
+
+Thank you for contributing to the community!
+```
+
+On failure, fall back to Option B.
+
+#### Option B: Open in Browser
+
+1. Save the case locally to the current directory as `case-skill-name-YYYYMMDD.md`
+
+2. Open the GitHub Discussions page:
+```bash
+xdg-open "https://github.com/HaoxuanLiTHUAI/awesome_cognitive_and_neuroscience_skills/discussions/new?category=show-and-tell" 2>/dev/null || \
+open "https://github.com/HaoxuanLiTHUAI/awesome_cognitive_and_neuroscience_skills/discussions/new?category=show-and-tell" 2>/dev/null || \
+echo "Please open: https://github.com/HaoxuanLiTHUAI/awesome_cognitive_and_neuroscience_skills/discussions/new?category=show-and-tell"
+```
+
+3. Inform the user:
+```
+✅ Case saved to: case-skill-name-YYYYMMDD.md
+
+🌐 Opening GitHub Discussions in your browser...
+
+📋 Next steps:
+1. Title: "Community Case: [Skill Name]"
+2. Copy the content from case-skill-name-YYYYMMDD.md
+3. Paste it into the discussion body
+4. Click "Start discussion"
+
+Thank you for contributing to the community!
+```
+
+---
+
+## Case Format Template
+
+The submitted Discussion body uses this format:
+
+```markdown
+## Community Case: [skill-name]
+
+### Quick Info
+- **Skill used**: `[skill-name]`
+- **Scenario**: [selected option from Q2]
+- **Rating**: [stars from Q3, e.g., ⭐⭐⭐⭐]
+- **Most valuable**: [selected options from Q4]
+
+### Research Context
+> [User's research question and experimental setup — synthesized from conversation]
+
+### What the Skill Suggested
+- [Key recommendation 1]
+- [Key recommendation 2]
+- [Key recommendation 3]
+
+### What I Actually Did & Result
+> [User's experience applying the recommendations and the outcome]
+
+### User's Tips
+> [Optional: Additional insights the user wants to share with the community]
+
+---
+*Submitted via the `share-case` meta-skill.*
+```
+
+---
+
+## Privacy Principles
+
+- **Nothing is submitted without explicit user confirmation** after full preview
+- Users can remove any section or paragraph before submission
+- Users can anonymize dataset names, lab names, and participant identifiers
+- Users can choose to submit anonymously (no GitHub username attribution in the case body)
+- The skill never auto-submits — the user must explicitly approve

package/skills/01_Meta-Skills/share-usage/README.md

@@ -0,0 +1,63 @@
+# Share Usage Skill
+
+Generate and share anonymized statistics about your skill usage with the community.
+
+## Quick Start
+
+Simply say to Claude:
+```
+share my skill usage
+```
+
+or
+
+```
+generate usage report
+```
+
+## What This Does
+
+1. Analyzes your Claude Code logs
+2. Counts how many times you've used each skill from this repository
+3. Generates a completely anonymized report
+4. Optionally helps you share it with the community
+
+## Privacy
+
+The report is **completely anonymized** and includes ONLY:
+- Skill names and usage counts
+- Date range
+- Optional research domain tag
+- Optional comments
+
+**No personal information, project details, or conversation content is included.**
+
+## Example Report
+
+```markdown
+# Skill Usage Report
+
+**Time Period**: 2024-01-15 to 2024-03-03 (48 days)
+**Research Domain**: fMRI analysis
+
+## Summary
+- Total skill calls: 47
+- Unique skills used: 12
+- Most used skill: fmri-glm-analysis-guide (15 times)
+
+## Top 10 Skills
+1. fmri-glm-analysis-guide: 15 uses
+2. fmri-preprocessing-pipeline-guide: 8 uses
+3. cogsci-statistics: 6 uses
+...
+```
+
+## Why Share?
+
+Sharing your usage report helps:
+- Maintainers understand which skills are most valuable
+- Other researchers discover useful skills
+- Guide future skill development priorities
+- Build a stronger community
+
+**Sharing is completely optional!**