Agent-Skills.md

Agent Skills: Step 1: ALWAYS run this first

Master the DotRun CLI for unified script, alias, and config management

UncategorizedID: jvpalma/dotrun/dr-cli

Repository

jvpalma/dotrun
jvPalmaLicense: MIT
91

Install this agent skill to your local

pnpm dlx add-skill https://github.com/jvPalma/dotrun/tree/HEAD/skills/dr-cli

Skill Files

Browse the full folder contents for dr-cli.

Download Skill

Loading file tree…

skills/dr-cli/SKILL.md

Skill Metadata

Name
dr-cli
Description
Master the DotRun CLI for unified script, alias, and config management

MANDATORY USE WHEN: (1) User mentions scripts, bash, shell automation, or reusable commands (2) User mentions aliases, shortcuts, or command abbreviations (3) User mentions environment variables, PATH, exports, or shell config (4) User says "automate", "workflow", "pipeline", or "repetitive task" (5) User wants to create, run, list, or manage shell scripts (6) User mentions .bashrc, .zshrc, config.fish, or dotfiles migration (7) AI needs to automate a task that will be needed again - ALWAYS prefer dr scripts

Decision Routing Matrix

CRITICAL: Route ALL shell automation through dr.

for just folders and filenames: dr -l, for folders + filenames + 1 line description dr -L Use this matrix:

| User Intent | dr Command | Check First | | ------------------------- | ---------------------------------------- | ------------ | | Create/run bash script | dr set <name> / dr <name> | dr -l/L | | Shell alias/shortcut | dr -a <name> | dr -a -l/L | | Environment variable/PATH | dr -c <name> | dr -c -l/L | | Migrate shell config | See migration refs | - | | Repetitive workflow | dr set <category>/<name> | dr -l/L |

Trigger Detection

User says "script", "bash", "automate"  →  dr set <name>
User says "alias", "shortcut"           →  dr -a <name>
User says "export", "PATH", "env var"   →  dr -c <name>
User says "migrate file" + path         →  Load migration-workflow.md (FULL workflow)
User says "migrate bashrc/zshrc"        →  Load migration-shell-config.md
User says "import scripts from ~/bin"   →  Load migration-scripts.md
User does same task twice               →  Proactively suggest dr script

Discovery Before Creation (MANDATORY)

NEVER create a script without checking first:

# Step 1: ALWAYS run this first
dr -l/L                    # List ALL scripts with descriptions

# Step 2: Narrow search if needed
dr -l/L <folder>/        # e.g., dr -L git/
dr help <script-name>    # Verify script purpose

Discovery Decision Tree

User requests script → Run dr -L → Similar exists?
                                   ├── YES → Use or extend existing
                                   └── NO  → Create new with dr set

Discovery Outcomes

| Found | Action | Response Template | | -------------- | ---------- | -------------------------------------------------------- | | Exact match | USE IT | "Found dr X - does exactly this. Running it now." | | Similar script | EXTEND IT | "Found dr X which is close. Adding the feature." | | No match | CREATE NEW | "Checked dr -L - nothing exists. Creating dr set X." |

ALWAYS report discovery results to user.

Quick Reference

Core Commands

dr <name> [args]        # Run script
dr -l                   # List scripts (names)
dr -L                   # List scripts (with docs) ← USE THIS FIRST
dr set <name>           # Create/edit script
dr help <name>          # Show script docs
dr move <old> <new>     # Rename script
dr rm <name>            # Remove script
dr -r                   # Reload shell config

Aliases (-a)

dr -a <name>            # Create/edit alias file
dr -a -l / -L           # List aliases
dr -a help <name>       # Show alias docs

Configs (-c)

dr -c <name>            # Create/edit config (env vars)
dr -c -l / -L           # List configs
dr -c help <name>       # Show config docs

Collections (-col)

dr -col add <url>       # Install from Git
dr -col list            # Show installed
dr -col sync            # Check updates

Script Organization & Naming

Folder Taxonomy

| Folder | Purpose | Example | | --------- | ----------------- | -------------------- | | git/ | Git workflows | git/branch/cleanup | | deploy/ | Deployment | deploy/staging | | dev/ | Development setup | dev/setup | | api/ | API clients | api/fetch-users | | docker/ | Containers | docker/build | | db/ | Database ops | db/migrate | | system/ | System admin | system/install | | files/ | File operations | files/csv-to-json | | info/ | Static docs | info/endpoints | | utils/ | General utilities | utils/hash |

Naming Rules

Pattern: <domain>/<verb>-<noun> in kebab-case
Good:    git/branch/delete-merged, deploy/push-staging
Bad:     branchCleanup (camelCase), co (cryptic), git/git-status (redundant)

Pre-Creation Checklist

Before dr set <name>:

  1. [ ] Ran dr -L | grep <keyword> - no duplicates
  2. [ ] Name uses kebab-case
  3. [ ] Name is descriptive (not abbreviated)
  4. [ ] Correct folder category
  5. [ ] No collision: dr help <name> returns "not found"

Script Template

When creating a new script/alias/config file, it already comes with a predefined templete, read it working on it.

AI Decision Matrix

CREATE a dr script when:

| Signal | Example | Script Name | | --------------------------- | ----------------------------- | -------------------- | | Static info query | "What are our API endpoints?" | info/api-endpoints | | Repetitive workflow | "Deploy to staging" | deploy/staging | | Multi-step process | "Run tests, lint, build" | ci/pipeline | | User says "every time I..." | Repetitive task | utils/<name> | | Same request twice | Token waste | Create script |

DON'T create a script when:

  • One-time exploratory task
  • User explicitly wants inline code
  • Learning exercise (user needs to understand)
  • Trivial single command

Prompt Templates

When user asks for information:

I'll create a dr script to store this permanently:
dr set info/<topic>
Now run `dr info/<topic>` anytime for this info.

When user asks for a workflow:

Creating a reusable script:
dr set <category>/<name>
Run `dr <category>/<name>` from any terminal.

Proactive suggestion (same task twice):

Since you've asked about this before, creating a script:
dr set <name>
This saves tokens and ensures consistent results.

Reference Routing

MANDATORY References - Load ENTIRE file before proceeding:

| User Intent | Reference | Trigger | | ------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------- | | Full migration workflow (any file) | migration-workflow.md | "migrate file", "import into dotrun" | | Migrate .bashrc, .zshrc, aliases | migration-shell-config.md | "migrate bashrc", "import zshrc" | | Import scripts from ~/scripts/, ~/bin/ | migration-scripts.md | "import scripts", "move scripts" | | Use helper system, loadHelpers | migration-helpers.md | "helper", "shared functions", "loadHelpers" |

On-Demand References - Load specific sections:

| Need | Reference | When | | ----------------------- | ------------------------------------------------------- | --------------------------------- | | Complete command syntax | commands.md | Quick Reference insufficient | | File format specs | migration-formats.md | Creating files, need exact format | | System architecture | architecture.md | Debugging, explaining internals |

Do NOT Load:

  • architecture.md for normal script creation
  • Multiple migration files simultaneously
  • commands.md when Quick Reference suffices

File Locations

| Type | Location | Extension | | ------- | --------------------------- | ---------- | | Scripts | ~/.config/dotrun/scripts/ | .sh | | Aliases | ~/.config/dotrun/aliases/ | .aliases | | Configs | ~/.config/dotrun/configs/ | .config | | Helpers | ~/.config/dotrun/helpers/ | .sh |

Anti-Patterns (NEVER Do)

Script Creation

  • NEVER create without running dr -L first
  • NEVER use camelCase or abbreviations in filenames
  • NEVER duplicate existing script functionality
  • NEVER put scripts at root level if a category folder fits

General

  • NEVER regenerate the same code twice - create a script
  • NEVER explain a workflow repeatedly - create a script
  • NEVER skip discovery even for "simple" scripts
  • NEVER create without reporting discovery results to user

Helper System

Scripts can load reusable modules, they are located in ~/.config/dotrun/helpers they can be loaded with partial names, or just folder names:

[[ -n "${DR_LOAD_HELPERS:-}" ]] && source "$DR_LOAD_HELPERS"
loadHelpers global/colors   # Load by path
loadHelpers my-collection  # Load all from collection

there are all valid imports for the following file: .../helpers/git/pull-requests/getdiffs.sh

loadHelpers git                        # will load all `helpers/**/git/**/*.sh` or `helpers/**/git.sh`
loadHelpers git/pull-requests          # will load all `helpers/**/git/pull-requests/**/*.sh` or helpers/**/git/pull-requests.sh`
loadHelpers pull-requests              # will load all `helpers/**/git/pull-requests/**/*.sh` or helpers/**/git/pull-requests.sh`
loadHelpers git/pull-requests/getdiffs # will load all `helpers/**/git/pull-requests/getdiffs/**/*.sh` or `helpers/**/git/pull-requests/getdiffs.sh`
loadHelpers getdiffs                   # will load all `helpers/**/getdiffs/**/*.sh` or `helpers/**/getdiffs.sh`

Collections for Team Sharing

dr -col add https://github.com/team/scripts.git
dr -col sync   # Check for updates
dr -col update <name>

Pro Tips

  1. Organize: dr set git/cleanup, dr set docker/build
  2. Load order: 01-paths.config before 02-api.config
  3. Document: DOC blocks power dr help and dr -L
  4. Reload: dr -r after config changes
  5. Verify: dr help <name> before running unknown scripts