planning-with-files/docs/gemini.md

Gemini CLI Setup

This guide explains how to install and use planning-with-files with Gemini CLI.

Prerequisites

• Gemini CLI v0.23 or later
• Agent Skills enabled in settings

Enable Agent Skills

Agent Skills is an experimental feature. Enable it first:

# Open settings
gemini /settings

# Search for "Skills" → Toggle "Agent Skills" to true → Press Esc to save

Or edit ~/.gemini/settings.json:

{
  "experimental": {
    "skills": true
  }
}

Installation Methods

Method 1: The Agent Skills standard path (Recommended since v3.7.0)

Gemini CLI reads the cross-tool .agents/skills/ layout natively (the alias takes precedence over .gemini/skills/), and this repo ships the current, version-locked skill there. Either install route lands the up-to-date skill:

# via the skills installer (targets Gemini among 70+ agents)
npx skills add OthmanAdi/planning-with-files

# or from GitHub, pointing at the standard layout
gemini skills install https://github.com/OthmanAdi/planning-with-files --path .agents/skills/planning-with-files

The historical .gemini/skills/ variant in this repo is intentionally version-lagged and kept only for existing installs; new installs should use the standard path above, which is bumped with every release.

Method 2: Manual Installation (User-level)

# Clone the repository
git clone https://github.com/OthmanAdi/planning-with-files.git

# Copy the current skill from the standard layout to the Gemini skills folder
cp -r planning-with-files/.agents/skills/planning-with-files ~/.gemini/skills/

Method 3: Manual Installation (Workspace-level)

For project-specific installation:

# In your project directory
mkdir -p .gemini/skills

# Copy the current skill from the standard layout
cp -r /path/to/planning-with-files/.agents/skills/planning-with-files .gemini/skills/

Verify Installation

# List all skills
gemini skills list

# Should show:
# - planning-with-files: Implements Manus-style file-based planning...

Or in an interactive session:

/skills list

Skill Discovery Tiers

Skills are loaded from three locations with this precedence:

Tier	Location	Scope
Workspace	.gemini/skills/	Project-specific (highest priority)
User	~/.gemini/skills/	All projects
Extension	Bundled with extensions	Lowest priority

Higher-precedence locations override lower ones when names conflict.

Usage

Automatic Activation

Gemini will automatically detect when to use this skill based on the task description. For complex multi-step tasks, it will prompt you:

Gemini wants to activate skill: planning-with-files
Purpose: Implements Manus-style file-based planning for complex tasks
Allow? [y/n]

Manual Activation

You can also manually enable/disable skills:

/skills enable planning-with-files
/skills disable planning-with-files
/skills reload

Hooks (v2.26.0)

Gemini CLI supports hooks — lifecycle events that run shell scripts automatically. This skill ships with a settings.json that configures 4 hooks:

Hook Event	What It Does
SessionStart	Recovers selected context from project planning files without reading agent session stores
BeforeAgent	Injects the first 30 lines of task_plan.md into the user turn through hookSpecificOutput.additionalContext
AfterTool	Reminds to update progress.md after file changes
SessionEnd	Reports completion status during shutdown; this is advisory and user-facing only

Gemini's event-specific output schema matters here: BeforeAgent and AfterTool send model context through hookSpecificOutput.additionalContext. BeforeTool is reserved for tool validation/argument rewriting, and BeforeModel accepts request/response overrides rather than an additionalContext field.

Local agent session history is not part of automatic startup. Explicit session-catchup.py --metadata <project> reads same-project local session records and emits aggregate counts only. Use --replay for bounded nonce-framed excerpts. The catchup path contains no network request or upload operation.

Installing Hooks

Copy the hooks configuration to your project:

# Copy settings.json (merges with existing settings)
cp /path/to/planning-with-files/.gemini/settings.json .gemini/settings.json

# Copy hook scripts
cp -r /path/to/planning-with-files/.gemini/hooks .gemini/hooks

Or for user-level hooks:

# Copy to user settings (applies to all projects)
cp /path/to/planning-with-files/.gemini/settings.json ~/.gemini/settings.json
cp -r /path/to/planning-with-files/.gemini/hooks ~/.gemini/hooks

Note: If you already have a settings.json, merge the "hooks" key manually.

---

How It Works

1. Session Start: Gemini loads skill names and descriptions, hooks run session recovery
2. Task Detection: When you describe a complex task, Gemini matches it to the skill
3. Activation Prompt: You approve the skill activation
4. Instructions Loaded: Full SKILL.md content is added to context
5. Execution: BeforeAgent re-injects task_plan.md context each user turn; AfterTool reminds the agent to record progress after file changes

Skill Structure

.gemini/
├── settings.json             # Hook configuration (v2.26.0)
├── hooks/                    # Hook scripts
│   ├── session-start.sh      # Session recovery
│   ├── before-agent.sh       # Turn-level plan context injection
│   ├── after-tool.sh         # Progress update reminder
│   └── session-end.sh        # Advisory completion status
└── skills/planning-with-files/
    ├── SKILL.md              # Main skill instructions
    ├── templates/
    │   ├── task_plan.md      # Phase tracking template
    │   ├── findings.md       # Research storage template
    │   └── progress.md       # Session logging template
    ├── scripts/
    │   ├── init-session.sh   # Initialize planning files
    │   ├── check-complete.sh # Verify completion
    │   ├── init-session.ps1  # Windows PowerShell version
    │   └── check-complete.ps1
    └── references/
        ├── reference.md      # Manus principles
        └── examples.md       # Real-world examples

Sharing Skills with Claude Code

If you use both Gemini CLI and Claude Code, you can share skills:

# Create symlink (Linux/macOS)
ln -s ~/.claude/skills ~/.gemini/skills

# Or copy between them
cp -r ~/.claude/skills/planning-with-files ~/.gemini/skills/

Troubleshooting

Skill not appearing

1. Check skills are enabled: gemini /settings → Search "Skills"
2. Verify installation: gemini skills list
3. Reload skills: /skills reload

Skill not activating

• Make sure your task description matches the skill's purpose
• Try manually enabling: /skills enable planning-with-files

Path issues on Windows

Use PowerShell:

# Copy to user skills
Copy-Item -Recurse -Path ".\.gemini\skills\planning-with-files" -Destination "$env:USERPROFILE\.gemini\skills\"

Resources

• Gemini CLI Documentation
• Agent Skills Guide
• Hooks Guide
• Skills Tutorial