yu-iskw executing-pi-agent
Purpose
Use this skill to perform coding, review, research, or automation tasks through the pi CLI. Prefer explicit tool allowlists so each invocation receives only the capabilities required for the task.
Pi implements the Agent Skills standard and can also consume compatible SKILL.md files directly. This skill covers the other direction: invoking Pi as an execution agent from another coding-agent workflow.
Security Model
Pi runs with the operating-system permissions of the user that launches it. Project trust controls whether project-local settings, skills, extensions, and related resources are loaded; it is not a sandbox and does not restrict what enabled tools can do.
For untrusted repositories, unattended execution, or high-impact tasks, run Pi inside an external containment boundary such as a container, VM, micro-VM, or policy-controlled sandbox. Mount only the required workspace paths and pass only the minimum credentials and network access needed.
Capability Tiers
| Tier | Capability | Pi tools | Approval required | Typical tasks |
|---|---|---|---|---|
| 0 | Observe | read,grep,find,ls |
No | Code review, audits, architecture analysis, local research |
| 1 | Edit | read,grep,find,ls,edit,write |
Yes | Refactoring, documentation, mechanical fixes |
| 2 | Execute | Add bash only when required |
Yes (High Risk) | Tests, builds, dependency changes, scripted automation |
Implementation Workflow
1. Analyze the request
Determine the minimum actions required:
- Read/search/list only -> Tier 0.
- Workspace file modifications without shell execution -> Tier 1.
- Shell commands, tests, builds, package managers, Git operations, or other process execution -> Tier 2.
If the task can be completed at a lower tier, use the lower tier.
2. Approval protocol
Obtain explicit user approval before Tier 1 or Tier 2 execution when the calling environment has not already obtained approval for the requested mutation or command execution.
Do not interpret Pi project trust as approval to modify files, execute commands, access secrets, or perform external side effects.
3. Execute with an explicit allowlist
# Tier 0: read-only analysis
pi --tools read,grep,find,ls -p "<prompt>"
# Tier 1: workspace editing without shell execution
pi --tools read,grep,find,ls,edit,write -p "<prompt>"
# Tier 2: shell execution explicitly enabled
pi --tools read,grep,find,ls,edit,write,bash -p "<prompt>"
Prefer --tools over relying on the default built-in tool set. If no tools are required, use --no-tools.
4. Validate the result
After Pi finishes:
- Inspect changed files or generated output.
- Run only the validation commands required by the task.
- Report changes, validation results, and any unresolved risks.
- Escalate capabilities only if the current tier cannot complete the task.
Skill Discovery Compatibility
Pi discovers Agent Skills from locations including:
~/.pi/agent/skills/~/.agents/skills/.pi/skills/.agents/skills/- package-provided
skills/directories orpi.skillspackage metadata - explicit
--skill <path>arguments
Use --skill <path> when a workflow should load a specific skill explicitly. Use --no-skills when automatic skill discovery is undesirable; explicit --skill arguments remain additive.
Security Rules
- ALWAYS select the minimum required tool allowlist.
- DO NOT enable
bashfor analysis-only or edit-only tasks. - DO NOT treat project trust as a sandbox or execution authorization boundary.
- DO NOT expose broad credentials or host filesystem mounts to unattended Pi sessions unless required.
- PREFER external containment for untrusted repositories, generated code that will not be closely monitored, and unattended automation.
- REVIEW diffs and command output before treating a task as complete.
Examples
Refer to references/usage-examples.md for concrete scenarios.