Learn how to build a fork terminal skill from scratch—spawn new terminal windows, run CLI commands, and automate Git commits with raw agentic coding.

Fork Terminal Mastery: Build an Agentic Skill from Scratch

Published by Brav

TL;DR

• Build a terminal-forking agent that launches new windows on macOS and Windows.
• Automate Git commits and cloud commands with a single skill file.
• Use raw agentic coding for fast, reusable workflows.
• Cross-platform: macOS, Windows, Linux.
• Step-by-step guide with directory layout, enable flags, and security best practices.

Why this matters

I’ve seen countless developers struggle with reusable prompts and code. They spend hours writing the same boilerplate, juggling permissions, and deploying skills on different machines. This skill turns the process into a single, consistent, and reusable package.

• Lack of reusable prompts and code → you now keep a single prompt per command that can be dropped into any project.
• Difficulty deploying skills → all you need is a skill.md and a couple of tools; nothing else.GitHub — Documentation (2024)
• Complex skill structure → a clear four-folder layout (skill.md, tools/, prompts/, cookbook/) keeps everything tidy.
• Cross-platform support → macOS uses osascript, Windows uses PowerShell, Linux falls back to xterm.
• Agent orchestration → raw agentic coding eliminates the overhead of a separate orchestrator.
• Permission handling & Git → the skill commits changes automatically, so you never lose a tweak.Git — Git documentation (2024)
• Summarizing context → a fork summary prompt keeps new agents in sync with the conversation.

Core concepts

1. Skill directory
   The skill lives in a repo. At the root you keep a skill.md that declares the skill name, version, and a brief description. Under it you create three folders:

   • tools/ – small JSON files that expose external commands or APIs.
   • prompts/ – reusable prompt templates that the agent loads on demand.
   • cookbook/ – step-by-step recipes that illustrate how to invoke the skill.

2. Raw agentic coding
   Instead of letting an orchestrator decide what to run, the skill itself contains the logic. This means fewer moving parts, less latency, and the ability to hook directly into the model’s chat. The skill’s main file is a single-file Python script run by Astral UV, a lightweight wrapper that ships the script and any dependencies in one binary.Astral UV — Documentation (2023)[STALE_SOURCE]

3. Astral UV
   Astral UV packages your Python script and its libraries into a single executable. It’s perfect for a skill that needs to run on a bare terminal without installing Python first. You only need to pip install astral-uv once.

4. Forking terminal windows
   On macOS the skill uses osascript to open a new Terminal.app window. On Windows it calls powershell.exe -NoExit. The agent then spawns a new child process that runs the next skill invocation. This gives you a fresh context for each sub-task, mirroring how you’d open a new terminal manually.

5. Enable flags
   The skill has an enable.yaml that toggles whether the Gemini CLI, Codex CLI, or Cloud Code agent is active. Switching between them is as simple as editing a line:

   gemini_cli: true
   codex_cli: false
   cloud_code: false
   

6. Progressive disclosure
   Each cookbook recipe is broken into small steps. The skill shows you the next instruction only after you finish the current one. That reduces cognitive load and helps the agent focus on the immediate goal.

7. Summarizing context
   When a new agent is spawned, the skill sends a fork summary prompt that uses a YAML template to embed the last few turns of the conversation. This ensures the child agent inherits the knowledge it needs without pulling the entire chat history.

How to apply it

1. Create the repo

   mkdir fork-terminal-skill && cd fork-terminal-skill
   git init
   

2. Add skill.md

   ---
   name: fork-terminal
   version: 1.0.0
   description: |
     Spawn a brand new terminal window and run any CLI command with ease.
   ---
   

3. Set up tools/
   Create tools/gemini_cli.yaml:

   name: gemini-cli
   type: exec
   command: "gemini-cli --model {{model}} --prompt '{{prompt}}'"
   

   Do the same for Codex and Cloud Code.

4. Write prompts
   In prompts/exec_help.md:

   Execute the following command and return its help text: {{command}}
   

5. Cookbook recipes
   In cookbook/curl_google.md:

   1. Ask the agent: "Run ***curl google.com*** and capture the output."
   2. Verify the HTTP status.
   3. Commit the result to git.
   

6. Enable flags
   Create enable.yaml:

   gemini_cli: true
   codex_cli: false
   cloud_code: false
   

7. Prime the agent
   Run the prime command so the agent loads all tools and prompts:

   astral-uv run prime
   

8. Execute

   astral-uv run fork-terminal -- command="curl google.com"
   

   The skill will:

   • Fork a new terminal window.
   • Read curl –help to gather usage.
   • Execute the command.
   • Capture stdout/stderr.
   • Commit changes to Git automatically.Git — Git documentation (2024)

Markdown table – Tool comparison

Gemini CLI uses the Google Gemini API Google — Gemini API (2024)

Pitfalls & edge cases

Quick FAQ

1. How do I set up the fork terminal skill on macOS?
   Install osascript (built-in), install astral-uv, and run the prime command. The skill will use osascript -e ’tell application “Terminal” to do script “bash”’ to open a new terminal.
2. Can the skill run on Windows PowerShell?
   Yes. The skill contains a Windows-specific path: powershell.exe -NoExit. Make sure powershell.exe is in your PATH.
3. What are the security risks of running arbitrary CLI commands?
   Running arbitrary commands can expose your system to injection attacks. The skill mitigates this by reading the command’s –help first and by letting you enable or disable commands via enable.yaml.
4. How does the skill summarize conversation history?
   It sends a YAML-formatted prompt that contains the last 5 turns. The agent then uses that summary to initialize the new child agent.
5. How can I enable or disable the Gemini CLI in the skill?
   Edit enable.yaml to set gemini_cli: true/false. No restart is needed; the next run will respect the flag.
6. Does the skill automatically commit changes to Git?
   Yes. After executing a command that produces output, the skill runs git add . and git commit -m “Auto-commit by fork terminal skill”.

Conclusion

If you’re tired of copying prompts, juggling tools, and wrestling with permissions, this fork terminal skill is a game-changer. It gives you a single, reusable workflow that can spawn fresh terminals, run any CLI command, capture output, and commit changes—all in one go.

Next steps:

• Fork the repository and run prime.
• Try the curl google.com recipe in the cookbook.
• Experiment with enabling the Codex CLI to auto-generate code snippets.

Happy hacking, and may your terminal windows stay as fresh as your ideas.