← Back to Skills Marketplace
Amazing PsyCoder
by
soupandpsy
· GitHub ↗
· v1.2.0
· MIT-0
38
Downloads
0
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install amazing-psycoder
Description
Orchestrates psychological experiment creation by enforcing a 3-step chain: design via 5-phase programming, code generation, and mandatory code review for Ps...
README (SKILL.md)
Amazing PsyCoder — System Orchestrator
Version
v1.2 — stable, 2026-06-06.
Purpose
This is the single entry point for the Amazing PsyCoder experimental skill system. It orchestrates a mandatory sequential chain of three sub-skills that convert psychological experiment ideas into audited, production-quality code.
This skill does NOT generate code itself. It routes the user through the correct sequence and enforces the chain: Programming → Coder → Reviewer. No step may be skipped.
Platforms: Claude Code / Codex / Hermes / OpenClaw — follows the agentskills.io open standard. See PLATFORMS.md for platform-specific installation and tool mapping.
System Architecture
User describes experiment (English / 中文)
│
▼
┌──────────────────────────────────────┐
│ ① psych-experiment-programming │ Orchestration layer
│ Input: natural language description│ 5-phase design workflow
│ Output: config YAML + conditions │ Design Decision Registry
│ Gates: Gate 1→2→3→4→5 │ Progressive confirmation
└──────────────┬───────────────────────┘
│ config YAML (internal artifact, not shown to user)
▼
┌──────────────────────────────────────┐
│ ② psych-experiment-coder │ Code generation layer
│ Input: config YAML + conditions │ 12-step code template
│ Output: runnable code + README │ 4-layer priority architecture
│ Gate: 9-item post-generation check │ Canonical Code Skeleton
└──────────────┬───────────────────────┘
│ Runnable experiment code
▼
┌──────────────────────────────────────┐
│ ③ psych-experiment-code-reviewer │ Audit layer (final mandatory gate)
│ Input: code / config / plan │ 5 review modes
│ Output: audit report + readiness │ Platform-aware checks
│ Gate: 0 Critical + 0 Major │ Severity grading
└──────────────────────────────────────┘
All three steps are mandatory — none can be skipped. Programming → Coder → Reviewer. No experiment code is considered complete without passing reviewer audit with
ready_for_collectionorready_after_minor_fixes.
How to Use This Skill
When a user invokes this skill, determine where they are in the pipeline and route accordingly:
Routing Decision Tree
User request
│
├─ "I want to build an experiment" / "我要做一个…实验"
│ → Invoke psych-experiment-programming (start Phase 1)
│
├─ "Generate code for this config" / "生成代码"
│ → Check: has Programming Gate 5 passed?
│ Yes → Invoke psych-experiment-coder
│ No → Route back to psych-experiment-programming first
│
├─ "Review this experiment code" / "审计这个实验"
│ → Invoke psych-experiment-code-reviewer
│
├─ "I got an error" / "代码报错"
│ → Check the error type:
│ Design error → psych-experiment-programming
│ Code error → psych-experiment-coder (see Debugging & Iteration Loop)
│
├─ "Review found issues" / "审计不通过" / "代码有问题需要修"
│ → Check the severity:
│ Critical/Major issues → Fix in psych-experiment-coder, re-audit after
│ Minor only → User can collect data; fix when convenient
│
├─ "What paradigms are available?" / "有哪些范式"
│ → Show [Paradigm Coverage Matrix](#paradigm-coverage-matrix)
│
└─ "How does this system work?" / "这个系统怎么用"
→ Show system overview + three-step chain
Mandatory Execution Order
- First: Invoke
psych-experiment-programming— guide user through 5-phase design. Output: complete config YAML (internal, not shown to user) - Second: Invoke
psych-experiment-coder— generate platform code from config. Output:.py/.js/.m+ README - Third: Invoke
psych-experiment-code-reviewer— audit the generated code. Output: audit report + readiness label
Never skip a step. Never generate code before the trial window timeline is confirmed.
Design Principles (System-Wide)
| # | Principle | Description | Applies to |
|---|---|---|---|
| 1 | Output is deliverable | Every phase produces complete, usable artifacts | All |
| 2 | Progressive confirmation | Design decisions confirmed phase by phase; defaults flagged [ASSUMED] |
Programming |
| 3 | Decision traceability | Design Decision Registry records source of every decision | Programming |
| 4 | Skeleton-first generation | All code generation MUST start from platform spec Canonical Code Skeleton | Coder |
| 5 | Paradigms provide logic, skeleton provides API | Paradigm files define experiment logic; API patterns from spec skeleton | Coder |
| 6 | Anti-pattern zero-tolerance | time.sleep(), event.getKeys(maxWait=), KbCheck for RT, jsPsych.init(), WaitSecs — blocked |
Coder, Reviewer |
| 7 | Your experiment, our standards | User owns the experimental design; system guarantees code quality | All |
| 8 | Window timeline before code | No code generation before trial window timeline is validated | Programming, Coder |
| 9 | Post-generation audit mandatory | All generated code must pass through Reviewer before data collection | Coder, Reviewer |
| 10 | Input bounds output | Reviewer's conclusions cannot exceed what the input supports | Reviewer |
Red Lines (System-Wide Absolute Prohibitions)
These rules span all three skills. Violation is never acceptable:
| # | Rule | Owned by | Consequence of violation |
|---|---|---|---|
| R1 | No code generation before trial window timeline is complete | Programming | Structural errors, expensive late-stage fixes |
| R2 | No assumed response mapping | Programming | Guessing key mapping invalidates accuracy data |
| R3 | No time.sleep() in experiment code |
Coder | Blocks event loop, Escape unresponsive |
| R4 | No event.getKeys(maxWait=...) |
Coder | Blocks event loop |
| R5 | No data saved only at experiment end | Coder | Crash = all data lost |
| R6 | No silent filling of [MISSING] values |
Programming | Every gap must be resolved by asking user or offering flagged default |
| R7 | No Chinese/CJK text without explicit font | Coder | PsychoPy default font lacks CJK glyphs; text renders as tofu (□□□) |
| R8 | No skipping paradigm Must-Confirm items | Programming | Unconfirmed items produce broken experiments |
| R9 | No rt_onset omitted on response windows |
Coder | Missing/incorrect RT onset invalidates all reaction time data |
| R10 | No code delivery without Reviewer pass | All | All code must pass reviewer audit before data collection |
Code Generation Architecture (4-Layer Priority)
All platforms use the same 4-layer priority stack. When layers conflict, higher always wins:
Layer 1: spec/ ← Highest: API spec, anti-patterns, Canonical Code Skeleton
Layer 2: mapping/ ← Structural: config YAML fields → platform code structures
Layer 3: paradigms/ ← Paradigm logic: window sequence, accuracy rules, condition structure
Layer 4: demo/ ← Lowest: raw demo code, logic reference only, never API reference
Code generation priority: spec canonical skeleton > spec anti-patterns > config→code mapping > paradigm logic > demos
Platform Layer Fill Status
| Layer | PsychoPy | jsPsych | Psychtoolbox |
|---|---|---|---|
L1 spec/ |
✅ | ✅ | ✅ |
L2 mapping/ |
✅ | ✅ | ✅ |
L3 paradigms/ |
✅ 27 paradigms | ✅ 25 paradigms | ✅ 5 paradigms |
L4 demo/_raw/ |
✅ 45 .py |
✅ 23 .js |
✅ 100 .md |
Code Template (Overview)
All generated code follows a 12-step structure: imports → parameters → display setup → stimulus preloading → condition loading → helpers → instructions → practice → main loop (blocks → randomization → per-trial windows) → incremental data save → cleanup → package with README. The full template with detailed per-step requirements is in the coder SKILL.md.
Post-Generation Quality Gate (Overview)
Before delivery, all generated code must pass the 9-item Quality Gate defined in the coder SKILL.md. Covers: spec skeleton compliance, anti-pattern scan, API patterns, parameter placement, escape handling, RT source, incremental save, preloading, and CJK font config. Any failure = fix before delivery.
Review Modes and Readiness Labels
Review Modes (auto-selected by Reviewer)
| Mode | Input | Maximum label |
|---|---|---|
code-audit |
Complete experiment code | ready_for_collection |
config-audit |
Config YAML / trial timeline | pre_code_ready |
implementation-plan-review |
Pseudocode / architecture plan | pre_code_ready |
triage-only |
Natural-language description | None (missing-info list only) |
blocked |
Insufficient input | None (state what's needed) |
Readiness Labels
| Label | Meaning |
|---|---|
ready_for_collection |
Zero Critical + zero Major — can collect data |
ready_after_minor_fixes |
Only Minor issues remain |
not_ready_for_collection |
Critical or Major issues exist — do NOT collect |
pre_code_ready |
Design complete, ready for code generation |
needs_experiment_info |
Key design information missing |
blocked |
Input insufficient for any review |
Severity Classification
| Severity | Definition | Can collect data? |
|---|---|---|
| Critical | Invalidates all data; must fix before any collection | No |
| Major | Degrades data quality; fix before formal collection | No |
| Minor | Does not affect data quality; fix when convenient | Yes |
Paradigm Coverage Matrix
Core Paradigms (14) — Full Programming-Layer Spec
All 10 required sections filled (When to Use, Core Logic, Must Confirm, Do Not Assume, Condition File Columns, Trial Window Timeline, Data Output Columns, Randomization Checks, Common Failure Modes, Example):
Go/No-go · Navon · Priming · Stroop · Eriksen Flanker · Simon · Rating · Stop-signal · IAT · N-back · Dot-probe · Visual Search · Task Switching · EAST
Extended Paradigms (24) — Programming-Layer Reference Descriptions
Antisaccade · ANT · BART · Bilingual Stroop · Change Detection · Children Flanker · Choice RT · Climate Reflection · CPT · Corsi Blocks · Cyberball · Delay Discounting · Drag and Drop · Mental Rotation · Multisensory Nature · Numerical Stroop · Phone a Friend · Posner Cuing · Psychophysics Staircase · Rating to Choice · Sternberg · Ultimatum Game · WCST · Writing Distraction
Paradigm Count Explained
| Layer | Count | What they are |
|---|---|---|
| Programming paradigms/ | 38 (14 core + 24 extended) | Design references for the 5-phase workflow. Apply to ALL platforms |
| Coder psychopy/paradigms/ | 27 | PsychoPy code references with platform-specific generation logic |
| Coder jspsych/paradigms/ | 25 | jsPsych code references with timeline plugins |
| Coder psychtoolbox/paradigms/ | 5 | PTB code references; most paradigms use 12-step template for manual adaptation |
Cross-Platform Mandatory API Quick Reference
| Dimension | PsychoPy | jsPsych (7.x) | Psychtoolbox |
|---|---|---|---|
| Keyboard | keyboard.Keyboard(backend='ptb') |
Plugin class references | KbQueueCreate + KbQueueCheck |
| RT source | key.rt (USB HID async) |
data.rt (automatic) |
firstPress - VBLTimestamp |
| RT origin | win.callOnFlip(kb.clock.reset) |
Stimulus onset (automatic) | VBLTimestamp = Screen('Flip') return |
| Timing loop | CountdownTimer |
trial_duration parameter |
vbl + (waitframes-0.5)*ifi |
| Data save | try/finally + per-trial flush |
on_finish callback |
try/catch + fopen/fprintf/fclose |
| Quit | Escape check in every loop | 'escape' in choices |
KbCheck(KbName('ESCAPE')) |
| Cleanup | win.close() + core.quit() |
jsPsych.endCurrentTimeline() |
sca + Priority(0) + ShowCursor |
| CJK font | FONT_CONFIG toggle + TextBox2 |
CSS font-family |
Screen('TextFont') + TextStyle |
Inter-Skill Communication Protocol
Programming → Coder
- Artifact: Complete
config.yaml(internal, never shown to user) - Precondition: Gate 5 passed (user confirmed full Design Decision Registry)
- Coder's duty: Load config → select platform → copy skeleton → map code → Quality Gate → deliver
Coder → Reviewer
- Artifact: Generated experiment code (
.py/.js/.m) + condition files + README - Precondition: Coder's Post-Generation Quality Gate passed
- Reviewer's duty: Detect platform → load corresponding spec → audit each dimension → output graded report + readiness label
Shared Artifacts
| Artifact | Producer | Consumer | Format |
|---|---|---|---|
| config YAML | Programming | Coder | .yaml (internal, not displayed) |
| Condition files | Programming | Coder | .xlsx / .csv |
| Experiment code | Coder | Reviewer, User | .py / .js / .m |
| Experiment README | Coder | Reviewer, User | .md (alongside code) |
| Audit report | Reviewer | User | Markdown (graded + readiness label) |
Code Output Specification
Deliverables
Every code generation produces two files:
| File | Format | Content |
|---|---|---|
| Platform experiment file | .py / .js / .m |
Runnable code, all parameters at top, FONT_CONFIG toggle if CJK used |
| Experiment README | .md |
Window sequence diagram, condition/block structure, response rules, data columns, how to run, parameter line numbers, known limitations |
Language Consistency
Code comments and README language MUST match the user's language:
- 中文用户 → 中文 README + 中文代码注释
- English user → English README + English code comments
File Structure
amazing-psycoder-skills/
├── amazing-psycoder/ ← Entry orchestrator (this skill)
│ ├── SKILL.md
│ ├── PLATFORMS.md ← Platform adapter reference
│ ├── install.sh ← Cross-platform installer
│ ├── psych-experiment-programming/ ← ① Orchestration layer
│ │ ├── SKILL.md ← 5-phase workflow + 10 red lines
│ │ ├── README.md
│ │ ├── paradigms/ ← 38 paradigm reference files
│ │ └── references/ ← Design references (config-schema, timing, etc.)
│ ├── psych-experiment-coder/ ← ② Code generation layer
│ │ ├── SKILL.md ← Generation flow + 4-layer arch + 9-item gate
│ │ ├── README.md
│ │ ├── psychopy/ ← PsychoPy (full auto)
│ │ │ ├── spec/README.md ← Canonical Skeleton + anti-patterns
│ │ │ ├── mapping/README.md ← Config→code mapping
│ │ │ ├── paradigms/ ← 27 paradigm references
│ │ │ └── demo/_raw/ ← 45 demo .py files
│ │ ├── jspsych/ ← jsPsych
│ │ │ ├── spec/README.md ← Canonical Skeleton + anti-patterns
│ │ │ ├── mapping/README.md ← Config→timeline + migration table
│ │ │ ├── paradigms/ ← 25 paradigm references
│ │ │ └── demo/_raw/ ← 23 demo .js files
│ │ └── psychtoolbox/ ← PTB
│ │ ├── spec/README.md ← Canonical Skeleton + anti-patterns
│ │ ├── mapping/README.md ← Config→MATLAB + frame loops
│ │ ├── paradigms/ ← 5 paradigm references
│ │ └── demo/_raw/ ← 100 API demos by category
│ └── psych-experiment-code-reviewer/ ← ③ Audit layer
│ ├── SKILL.md ← 5 review modes + platform-aware audit
│ └── README.md
├── docs/ ← Multi-language READMEs
│ ├── README_EN.md
│ ├── README_ZH-HANT.md
│ ├── README_JA.md
│ ├── README_DE.md
│ └── README_FR.md
└── README.md ← Main README (简体中文)
When NOT to Use This Skill
- Quick PsychoPy/jsPsych/PTB API questions: Answer directly; don't invoke the full workflow
- General Python/JavaScript/MATLAB questions: Answer directly
- Non-experiment programming tasks: Not in scope
Usage Guidance
Install only if you are comfortable reviewing generated experiment code before running it or using it with participants. Pay particular attention to condition-file handling, avoid exec/globals-style variable injection, remove third-party tracking/geolocation snippets unless explicitly approved, and make sure any participant metadata collection, deception, and debriefing are covered by your study protocol.
Capability Tags
Capability Assessment
Purpose & Capability
The stated purpose is coherent: an orchestrator for designing, generating, and reviewing PsychoPy/jsPsych/Psychtoolbox experiments. However, the artifact includes large runnable demo/reference code with condition-file-driven dynamic execution and templates that collect participant/network metadata; these risks are relevant to the skill's generated outputs.
Instruction Scope
The top-level instructions disclose a mandatory Programming to Coder to Reviewer workflow and tell the coder to prefer canonical specs over demos. That mitigates some risk, but the reference layer still normalizes unsafe alternatives such as globals-based condition injection and includes full examples that could be copied into generated experiments.
Install Mechanism
install.sh copies the orchestrator and three subskills into local agent skill directories and overwrites existing same-named directories with rm -rf before copying. There is no network download, sudo use, or hidden dependency install, but users should know it replaces installed skills of the same names.
Credentials
Experiment code generation reasonably involves local files, stimuli, participant data, and browser/runtime APIs. The concern is that some templates load third-party assets or scripts and collect URL parameters, IP/geolocation, platform, user-agent, and frame-rate metadata without a strong minimization or consent requirement in the skill instructions.
Persistence & Privilege
No background workers, credential access, privilege escalation, or hidden persistence were found. Persistence is limited to installing skill directories and generated experiments writing local data files, which is expected for the stated purpose.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install amazing-psycoder - After installation, invoke the skill by name or use
/amazing-psycoder - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.2.0
Version 1.2.0 — Major system orchestration and documentation update.
- Introduces a strict three-step chain: Programming → Coder → Reviewer—each is mandatory, ensuring quality and audit for psychological experiment code.
- Adds detailed system architecture diagrams, explicit user routing logic, and precise “Red Lines”/prohibitions to prevent common code and design errors.
- Extends paradigm coverage references (now 38) and clearly states platform compatibility (PsychoPy, jsPsych, Psychtoolbox).
- Clarifies that this skill acts only as a router/orchestrator—never generating code directly.
- Implements robust decision traceability, mandatory audits, and a four-layer code generation architecture for all supported platforms.
Metadata
Frequently Asked Questions
What is Amazing PsyCoder?
Orchestrates psychological experiment creation by enforcing a 3-step chain: design via 5-phase programming, code generation, and mandatory code review for Ps... It is an AI Agent Skill for Claude Code / OpenClaw, with 38 downloads so far.
How do I install Amazing PsyCoder?
Run "/install amazing-psycoder" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is Amazing PsyCoder free?
Yes, Amazing PsyCoder is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does Amazing PsyCoder support?
Amazing PsyCoder is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created Amazing PsyCoder?
It is built and maintained by soupandpsy (@soupandpsy); the current version is v1.2.0.
More Skills