skill-safe-commands

name	skill-safe-commands
description	Centralized list of commands safe for auto-execution without user approval. Single source of truth.
tier	0
version	1.2

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:

## 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