# Skill Safe Commands

> Centralized list of commands safe for auto-execution without user approval. Single source of truth.

- Skill: `matrixfounder/skill-safe-commands` (Agent Skill)
- Install (CLI): `npx skillmds@latest add matrixfounder/skill-safe-commands`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matrixfounder/skill-safe-commands/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MatrixFounder (https://skillmd.com/u/matrixfounder)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/matrixfounder/skill-safe-commands

---

# Safe Commands Protocol

This skill defines **all commands that are SAFE TO AUTO-RUN** without user approval.

> [!IMPORTANT]
> **This is the single source of truth for Safe Commands.**
> All other skills and prompts should reference this skill instead of duplicating the list.

## Auto-Run Command Categories

| Category | Commands | Reason |
|----------|----------|--------|
| **Read-only** | `ls`, `cat`, `head`, `tail`, `find`, `grep`, `rg`, `fd`, `tree`, `wc`, `echo` | Do not modify state |
| **Symlink-aware** | `find -L`, `ls -L`, `rg --follow` / `rg -L`, `fd -L` | Read-only, but follow symlinks into framework dirs (`.agent/`, `.agents/`, `.cursor/skills/`, `System/`, `.agentic-development/`). Plain `find`/`ls`/`rg` do **not** descend into symlinked directories |
| **File info** | `stat`, `file`, `du`, `df` | Informational only |
| **Git read** | `git status`, `git log`, `git diff`, `git show`, `git branch`, `git remote`, `git tag` | Read-only git operations |
| **Archiving** | `mv docs/TASK.md docs/tasks/...`, `mv docs/PLAN.md docs/plans/...` | Documented, non-destructive moves (TASK/PLAN rotate in lockstep) |
| **Directory** | `mkdir -p docs/tasks`, `mkdir -p docs/plans`, `mkdir -p docs/architectures`, `mkdir -p .agent/skills/*` | Idempotent operations |
| **Tool calls** | `generate_task_archive_filename`, `list_directory`, `read_file` | Native tools |
| **Framework scripts** | `python3 .agent/skills/skill-session-state/scripts/update_state.py`, `python3 .agent/tools/task_id_tool.py`, `python3 .agent/tools/rebase_links.py`, `python3 .agent/skills/skill-creator/scripts/validate_skill.py`, `python3 .agent/skills/skill-creator/scripts/init_skill.py`, `python3 .agent/skills/artifact-formalizer/scripts/scan_register.py`, `python3 .agent/skills/artifact-formalizer/scripts/selftest_scan.py`, `python3 System/scripts/doctor.py` | Framework automation |
| **Testing** | `python -m pytest ...`, `npm test`, `npx jest`, `cargo test` | Tests don't modify source code |

> [!IMPORTANT]
> **`artifact-formalizer/evals/run_authoring.py` is deliberately NOT on this list.** The other two
> eval scripts read files and spawn nothing. `run_authoring.py` spawns `claude -p` once per arm per
> case and spends tokens, so it requires approval on every invocation.

## Pattern Matching Rules

Commands are safe if they match these patterns:

```
# Read-only filesystem
^(ls|cat|head|tail|find|grep|rg|fd|tree|wc|stat|file|du|df|echo)(?:\s|$)

# Symlink-aware read-only — framework dirs (.agent/, .agents/, System/, .agentic-development/) may be symlinks
^find\s+-L
^ls\s+-[a-zA-Z]*L
^rg\s+(--follow|-L)
^fd\s+-[a-zA-Z]*L

# Git read operations
^git\s+(status|log|diff|show|branch|remote|tag)

# Archiving (specific paths only)
^mv\s+docs/(TASK|PLAN)\.md\s+docs/(tasks|plans)/

# Directory creation (safe paths)
^mkdir\s+-p\s+(docs|\.agent|tests)/

# Python testing
^(python|python3)\s+-m\s+pytest
^cd\s+\.agent/tools\s+&&\s+python
^python3?\s+-c\s+'from\s+scripts\.tool_runner

# Node testing
^npm\s+test
^npx\s+jest

# Framework scripts
^python3\s+\.agent/skills/skill-session-state/scripts/update_state\.py
^python3\s+\.agent/tools/task_id_tool\.py
^python3\s+\.agent/tools/rebase_links\.py
^python3\s+\.agent/skills/skill-creator/scripts/(validate_skill|init_skill)\.py
^python3\s+\.agent/skills/artifact-formalizer/scripts/(scan_register|selftest_scan)\.py
^python3\s+\.agent/skills/artifact-formalizer/evals/(selftest_evals|grade_run)\.py
^python3\s+System/scripts/doctor\.py
```

## Implementation Guidelines

### For Agents (Runtime Behavior)
When calling `run_command` in **ANY** environment:
1. Check if the command matches the patterns above or the table.
2. If match found → Set `SafeToAutoRun: true`.
3. If no match → Set `SafeToAutoRun: false` (require approval).

> [!IMPORTANT]
> **Symlink-following is the default for framework paths.** When listing or
> searching `.agent/`, `.agents/`, `.cursor/skills/`, `System/`, or
> `.agentic-development/`, prefer the symlink-aware variants (`find -L`,
> `ls -L`, `rg --follow`) — a plain `find`/`ls`/`rg` silently skips symlinked
> directories. If a read-only probe returns **nothing** under a known
> framework directory, retry it **once** with symlink-following enabled before
> treating the path as empty or missing.

### For Users (Configuration)
> **Note for Agents:** Do NOT create configuration files (like `.cursorrules` or `AGENTS.md`) automatically. These are user-managed files.

**Cursor Users:**
- Add the patterns above to your `.cursorrules` or `AGENTS.md` file to enable auto-approval.

**Antigravity Users:**
- Add the command list below to "Allow List Terminal Commands" setting in IDE options:
  `ls,cat,head,tail,find,find -L,ls -L,grep,rg,rg --follow,fd,fd -L,tree,wc,stat,file,du,df,git status,git log,git diff,git show,git branch,git remote,git tag,mv docs/TASK.md,mv docs/PLAN.md,mkdir -p docs,mkdir -p .agent,mkdir -p tests,python -m pytest,python3 -m pytest,npm test,npx jest,cargo test`

### Troubleshooting
If the IDE still requests approval for commands listed here:
1. **Agent Behavior**: Ensure the Agent is actually setting `SafeToAutoRun: true` in the tool call. If the Agent sets it to `false`, the IDE *must* ask for approval regardless of the Allow List.
2. **Prefix Matching**: Some IDEs require exact matches. If `mv docs/TASK.md` works but `mv docs/TASK.md docs/tasks/foo.md` fails, check if the IDE supports regex/glob patterns or try shortening the allowed rule (e.g., `mv` only) if security policy permits.

## Integration

### How Other Skills Should Reference This

Instead of duplicating Safe Commands lists, use:

```markdown
## Safe Commands
See `skill-safe-commands` for the authoritative list of commands safe for auto-execution.
```

### Required by
- `skill-archive-task` — archiving commands
- `artifact-management` — file operations
- `developer-guidelines` — test commands
- All agent prompts — general command execution