Skills DirectoryCurated open-source Skills from GitHub
English

planning-with-filescommit a13b6be · v3.27.0SKILL.md · Task Breakdown

Planning with Files

Manages multi-step agent work in task_plan.md, findings.md and progress.md on disk so it can be recovered after interruptions.

Registers several lifecycle hooks; session-catchup.py can read same-project local session records, and --replay excerpts need explicit user approval.

npx skills add OthmanAdi/planning-with-files --skill planning-with-files
Permissions
  • read-repo
  • write-files
  • shell
  • network
Compatible with
Claude Code, Codex, Cursor, Copilot, OpenCode
GitHub
27.8k
Source
Community · Ahmad Othman Ammar Adi
Status
Scan passed
License
MIT
Category
Task Breakdown
Repository
github.com/OthmanAdi/planning-with-files/skills/planning-with-files

Core rule

Never start a complex task without task_plan.md, and re-read the plan before each decision.

Execution Phases

  1. Phase 01Restore state

    Find and reuse an existing plan; for a new task create the plan files with the initializer without overwriting existing ones.

  2. Phase 02Read before deciding

    Re-read the plan before decisions and write discoveries to findings.md after every two actions.

  3. Phase 03Update after acting

    After each phase, update progress.md and the plan's Next Step, and log every error.

  4. Phase 04Never repeat failures

    Follow the 3-strike protocol and change approach instead of retrying the same failure.

Permissions (summarised from SKILL.md)

CapabilityNeededDetails
File writesRequiredCreates and updates plan, findings and progress files in the project without overwriting existing plan files.
Command executionLimitedRuns its bundled shell/PowerShell scripts and registers hooks on prompt submit, tool use, stop and compaction; never runs commands declared in Markdown.
Network outboundNot requiredThe skill states it has no network upload path.

SKILL.md frontmatter (YAML)

SKILL.md frontmatter (YAML)commit a13b6be · v3.27.0
---
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
user-invocable: true
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
  UserPromptSubmit:
    - hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=userprompt; exit 0"
  PreToolUse:
    - matcher: "Write|Edit|Bash|Read|Glob|Grep"
      hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=pretool; exit 0"
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=posttool; exit 0"
  Stop:
    - hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=stop; exit 0"
  PreCompact:
    - matcher: "*"
      hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
  version: "3.27.0"
---

Related skills

A rule scan cannot catch every risk. Read this skill's SKILL.md and check its permissions before installing.
Markdown version GitHub