docs/installation.md
Complete installation instructions for planning-with-files.
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
That's it! The skill is now active.
Not every route delivers every surface. This matrix is the difference between "installed" and "fully working":
| Route | SKILL.md + scripts + templates | Slash commands (/plan-goal, /plan-loop, /plan-attest, /plan-doctor) | Hooks (plan injection, Stop check, PreCompact) |
|---|---|---|---|
Plugin: /plugin marketplace add + /plugin install | Yes | Yes | Yes |
npx skills add OthmanAdi/planning-with-files | Yes | No (commands/ is not copied) | Frontmatter hooks; see the two silent killers below |
ClawHub / manual skill copy to ~/.claude/skills/ | Yes | No | Frontmatter hooks; see below |
Two conditions can leave a skill-route install silently hook-less — everything looks installed, but no plan context is ever injected:
.claude/skills/ inside the repo) only activates after the project's trust dialog is accepted (hasTrustDialogAccepted). Headless or scripted sessions that never accepted trust load no project skills, and nothing prints an error.If hooks matter to you (they are the differentiating mechanism of this skill), install via the plugin route. Either way, verify with the doctor:
sh scripts/plan-doctor.sh # from your project root; reports resolution, injection, latency
Skill descriptions trigger probabilistically — in our July 2026 benchmark, unforced engagement was 60-67%, while an always-loaded rules-file instruction engaged 100% of the time. If you want the skill to fire every time a task is complex, add one line to your project's CLAUDE.md (or global ~/.claude/CLAUDE.md):
When a task needs 3+ steps or 5+ tool calls, invoke the planning-with-files skill first and keep task_plan.md current.
The skill description still handles discovery; the rules line makes engagement deterministic. Both together cost nothing when no complex task is running.
Install directly using the Claude Code CLI:
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
Advantages:
Clone or copy this repository into your project's .claude/plugins/ directory:
mkdir -p .claude/plugins
git clone https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
git submodule add https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
git clone https://github.com/OthmanAdi/planning-with-files.git
claude --plugin-dir ./planning-with-files
If you only want the skill without the full plugin structure:
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/skills/* ~/.claude/skills/
Extract just the skill directly into your current directory:
curl -L https://github.com/OthmanAdi/planning-with-files/archive/master.tar.gz | tar -xzv --strip-components=2 "planning-with-files-master/skills/planning-with-files"
Then move planning-with-files/ to ~/.claude/skills/.
After installation, verify the skill is loaded:
[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /planning-with-files/planning-with-files to manually invoke/plugin update planning-with-files@planning-with-files
cd .claude/plugins/planning-with-files
git pull origin master
cd ~/.claude/skills/planning-with-files
git pull origin master
/plugin uninstall planning-with-files@planning-with-files
rm -rf .claude/plugins/planning-with-files
rm -rf ~/.claude/skills/planning-with-files
See docs/windows.md for Windows-specific installation notes.
See docs/cursor.md for Cursor IDE installation.
See docs/codex.md for Codex IDE installation.
See docs/opencode.md for OpenCode IDE installation.
If installation fails, check docs/troubleshooting.md or open an issue at github.com/OthmanAdi/planning-with-files/issues.