experiment-scaffold

prateek's avatarfrom prateek

Create a new experiment workspace directory: initialize git, write an AGENTS.md goal doc, and create references/ with index.md + notes/links markdown plus GitHub repos cloned under references/repos (gitignored). Use when the user asks to spin up a scratch/research/experiment folder and provides repos, links, and/or notes to collect.

⭐0stars🔀3forks📁View on GitHub🕐Updated Jan 10, 2026
[Developer Tools]

When & Why to Use This Skill

The Experiment Scaffold skill is a powerful automation tool designed to streamline the initialization of research and development workspaces. It eliminates manual setup by automatically creating a structured directory environment, initializing Git, generating goal-oriented documentation (AGENTS.md), and organizing reference materials. By integrating GitHub repository cloning and markdown-based note-taking structures, it provides developers and researchers with a standardized, 'ready-to-code' foundation for any technical experiment or spike project.

Use Cases

  • Technical Research & Benchmarking: Quickly set up a dedicated workspace to compare different libraries or APIs, with all documentation, reference links, and source code repositories organized in a single, git-ignored structure.
  • AI & Machine Learning Experiments: Initialize a clean environment for testing new models or papers, automatically cloning relevant GitHub repos and creating a centralized AGENTS.md to track research goals and progress.
  • Rapid Prototyping: Spin up a 'scratch' folder for new project ideas with a standardized layout, ensuring that initial notes, external resources, and dependency source code are captured systematically from day one.
  • Code Reproduction & Debugging: Create isolated environments to reproduce specific issues or bugs, keeping all related reference materials and cloned upstream repositories neatly categorized for easy access.
nameexperiment-scaffold
description"Create a new experiment workspace directory: initialize git, write an AGENTS.md goal doc, and create references/ with index.md + notes/links markdown plus GitHub repos cloned under references/repos (gitignored). Use when the user asks to spin up a scratch/research/experiment folder and provides repos, links, and/or notes to collect."

Experiment Scaffold

Gather inputs

  • Experiment directory name (a single path segment; no /)
  • Goal (1–3 sentences: what you’re trying to learn/build/test)
  • GitHub repos (repeatable; owner/repo or URL)
  • Reference URLs (repeatable; blogs/docs/API pages)
  • Notes (repeatable; bullets)
  • Optional root directory to create the experiment in (default: current directory)

Run the scaffold script

The helper script is scripts/create_experiment.py (next to this SKILL.md). Run it with the extracted inputs.

Example:

python3 scripts/create_experiment.py \
  --root ~/experiments \
  --name vector-search \
  --goal "Evaluate hybrid search with embeddings vs BM25." \
  --repo openai/openai-python \
  --repo facebookresearch/faiss \
  --url https://platform.openai.com/docs/ \
  --note "Measure latency/recall across configs"

What it creates

  • <root>/<name>/.gitignore (ignores references/repos/)
  • <root>/<name>/AGENTS.md (goal + pointer to references/index.md)
  • <root>/<name>/references/index.md (inventory + clone status)
  • <root>/<name>/references/notes.md
  • <root>/<name>/references/links.md
  • <root>/<name>/references/repos/<owner>/<repo> (cloned; gitignored)

Cloning notes (gh, multiple accounts, SSH)

  • The script tries gh repo clone first and prefers SSH; it falls back if SSH/auth fails.
  • If a repo fails to clone and you have multiple GitHub accounts, check gh auth status and switch with gh auth switch -u <user>.
  • To default gh to SSH cloning, set gh config set git_protocol ssh.

Useful flags

  • --depth 0 for a full clone (default is shallow)
  • --no-clone to generate structure without cloning
  • --strict to stop on the first clone failure (otherwise record failures in references/index.md)