docs/gemini.md
This guide explains how to install and use planning-with-files with Gemini CLI.
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
}
}
gemini skills install https://github.com/OthmanAdi/planning-with-files --path .gemini/skills/planning-with-files
# Clone the repository
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy to Gemini skills folder
cp -r planning-with-files/.gemini/skills/planning-with-files ~/.gemini/skills/
For project-specific installation:
# In your project directory
mkdir -p .gemini/skills
# Copy skill
cp -r /path/to/planning-with-files/.gemini/skills/planning-with-files .gemini/skills/
# List all skills
gemini skills list
# Should show:
# - planning-with-files: Implements Manus-style file-based planning...
Or in an interactive session:
/skills list
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.
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]
You can also manually enable/disable skills:
/skills enable planning-with-files
/skills disable planning-with-files
/skills reload
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 context from previous session via session-catchup.py |
| BeforeTool | Reads first 30 lines of task_plan.md before write/read/shell operations |
| AfterTool | Reminds to update progress.md after file changes |
| BeforeModel | Injects current phase awareness before every model call (unique to Gemini!) |
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.
.gemini/
├── settings.json # Hook configuration (v2.26.0)
├── hooks/ # Hook scripts
│ ├── session-start.sh # Session recovery
│ ├── before-tool.sh # Plan context injection
│ ├── after-tool.sh # Progress update reminder
│ └── before-model.sh # Phase awareness (unique to Gemini)
└── 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
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/
gemini /settings → Search "Skills"gemini skills list/skills reload/skills enable planning-with-filesUse PowerShell:
# Copy to user skills
Copy-Item -Recurse -Path ".\.gemini\skills\planning-with-files" -Destination "$env:USERPROFILE\.gemini\skills\"