# Datalad Run

> >

- **Type:** Skill
- **Install:** `agentstack add skill-neuroanalytics-data-science-harness-datalad-run`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [neuroanalytics](https://agentstack.voostack.com/s/neuroanalytics)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [neuroanalytics](https://github.com/neuroanalytics)
- **Source:** https://github.com/neuroanalytics/data-science-harness/tree/main/plugins/datalad-cli/skills/datalad-run

## Install

```sh
agentstack add skill-neuroanalytics-data-science-harness-datalad-run
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill: datalad-run

Wrap a command in `datalad run` to record it in the dataset history with full provenance:
inputs consumed, outputs produced, and the exact command used. On success, DataLad
automatically stages and commits the outputs. On failure, nothing is committed.

## Steps

1. **Identify the command** — read `$ARGUMENTS` or extract from conversation context.
   If the command is ambiguous or missing, ask the user to specify the full command
   string before continuing.

2. **Verify DataLad context** — check whether the current working directory (or the
   project directory) is inside a DataLad dataset:
   ```bash
   ls .datalad/
   ```
   - **Dataset found**: continue.
   - **No dataset found**: ask the user:
     > "No DataLad dataset detected in the current directory. Would you like to:
     > 1. Initialize one here with `/datalad-init`
     > 2. Run the command bare (no provenance tracking)"
     Wait for their choice. If bare, run the command directly and stop.

3. **Check for unsaved changes** — run `datalad status`. If the output shows modified
   or untracked files, prompt:
   > "There are unsaved changes in the dataset. DataLad run records a clean snapshot
   > before executing. Save now with `datalad save -m \"...\"` first?"
   Wait for the user to either save or confirm they want to proceed anyway.

4. **Gather run parameters** — ask the user (or infer from context) for:
   - **`-i` (inputs)**: files or glob patterns the command reads (can be omitted if none)
   - **`-o` (outputs)**: files or glob patterns the command writes (required if outputs exist)
   - **`-m` (message)**: a meaningful description of what this run does (required)

   For pipelines with multiple stages, suggest wrapping as:
   ```
   bash -c 'cmd1 | cmd2'
   ```

   If the user wants to use `--explicit`: all declared output paths (`-o`) must be
   **pre-unlocked** before the run (`datalad unlock `). Without pre-unlocking,
   the run will fail with a locked-path error. Confirm outputs are unlocked before constructing
   the command.

4b. **Optional dry-run** — to verify the command before committing, suggest:
   ```
   datalad run --dry-run 
   ```
   This executes the command without creating a commit, letting the user confirm
   outputs are produced as expected before recording provenance.

5. **Construct and show the command** — build the full `datalad run` invocation and
   display it to the user before executing:
   ```
   datalad run \
     -m "" \
     [-i ] \
     [-o ] \
     ""
   ```
   Multiple `-i` and `-o` flags are allowed. Show the exact command, then ask:
   > "Ready to execute? (yes / edit)"

6. **Execute and report** — after user confirmation, run the constructed command.
   Report:
   - On **success**: the commit hash DataLad created, the output files recorded, and
     that the outputs are now tracked in the dataset history
   - On **failure**: that the command failed and nothing was committed; show the error
     output and suggest how to fix it

## Constraints

- Always show the full constructed `datalad run` command to the user before executing —
  never run silently.
- Never use `datalad run` for commands that produce no output files (e.g., `git log`,
  `ls`, `cat`, exploratory queries). Use bare Bash for those instead.
- Always require a meaningful `-m` message — never use empty or placeholder messages
  like "run" or "analysis".
- Never skip the unsaved-changes check — a dirty working tree can produce misleading
  provenance records.
- For pipeline commands (pipes, multi-step shell), always wrap as `"bash -c 'cmd1 | cmd2'"`.
- Load `${CLAUDE_PLUGIN_ROOT}/references/run-command.md` when the user asks about
  advanced flags (`--explicit`, `--expand`, `--dry-run`), replaying runs (`datalad rerun`),
  or recording download provenance (`datalad download-url`).
- Load `${CLAUDE_PLUGIN_ROOT}/../references/yoda-layout.md` when the user asks about
  YODA directory conventions, where outputs should go, or why inputs are subdatasets.
- Load `${CLAUDE_PLUGIN_ROOT}/../references/troubleshooting.md` when a run fails, the
  user has unlocked output files left over, or asks how to recover from a partial run.
- If the run fails with a "locked" or "permission denied" error on output files, the fix
  is: `datalad unlock `, then re-run. Load
  `${CLAUDE_PLUGIN_ROOT}/../references/troubleshooting.md` for the full recovery pattern.
- Load `${CLAUDE_PLUGIN_ROOT}/../references/global-options.md` when the user asks about
  debugging a failed run (`-l debug`), suppressing result output in CI (`-f disabled`),
  overriding annex config for a single run (`-c`), or running against a different working
  directory (`-C`).

## Replaying recorded runs (`datalad rerun`)

When the user wants to replay a previously recorded run:

1. **Identify the target commit** — ask the user for the commit SHA, or use the most
   recent `datalad run` commit if they say "the last run":
   ```bash
   git log --oneline --grep="datalad run" -5
   ```

2. **Construct the rerun command**:
   - Replay the most recent run: `datalad rerun`
   - Replay a specific commit: `datalad rerun `
   - Replay a range: `datalad rerun ..`

3. **Show and confirm** before executing — a rerun re-executes the original command
   with the same inputs and outputs, creating a new commit. This is not reversible.

4. **Report outcome** — on success, note the new commit SHA and that this replay is
   also recorded in dataset history (provenance chain). On failure, show the error.

Load `${CLAUDE_PLUGIN_ROOT}/references/run-command.md` for the full flag reference.

## Recording download provenance (`datalad download-url`)

When the user wants to download a file and record where it came from:

1. **Gather parameters**:
   - URL to download from
   - Local destination path (`--path`)
   - A meaningful message (`-m`)

2. **Construct command**:
   ```bash
   datalad download-url -m "" \
     --path  \
     
   ```

3. **Show and confirm** — this creates a DataLad commit recording the URL, content
   hash, and download time. The file is annexed automatically.

4. **After download** — suggest verifying with `datalad status` and `git annex whereis`.

Use this instead of `wget`/`curl` whenever the file's origin should be tracked in
dataset history (YODA P2: record data origins).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [neuroanalytics](https://github.com/neuroanalytics)
- **Source:** [neuroanalytics/data-science-harness](https://github.com/neuroanalytics/data-science-harness)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-neuroanalytics-data-science-harness-datalad-run
- Seller: https://agentstack.voostack.com/s/neuroanalytics
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.