Guide · Agent skill
How to use the Planning with Files (Arabic) agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The planning-with-files-ar skill gives an AI agent a written working memory: it keeps a task plan, a findings file and a progress log as plain Markdown files inside your project. It is written in Arabic and is meant for research or work that needs five or more tool calls. After this guide you will know what the skill does, how to install it, how to trigger it, and which safety points to check before you rely on it.
Planning with Files (Arabic)OthmanAdi/planning-with-files · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip the skill folder.
- 2Place the skill. Put it in ~/.claude/skills/ for all projects, or in the project's .claude/skills/ folder for one project. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Check requirements. Confirm you have a bash or sh shell and a host with hook support, such as Claude Code.
- 4Ask for a multi-step task. Describe a task that needs five or more tool calls in plain language.
- 5Create or resume the plan. Let the agent use init-session.sh for a new task or resume the existing plan folder.
- 6Validate the plan. Run check-complete.sh --validate on the plan file to confirm the phase format.
- 7Review progress. Read progress.md and task_plan.md to see status and what changed.
What does the skill make the agent do?
Instead of holding a long task only in its conversation memory, the agent writes its plan to files on disk: task_plan.md, findings.md and progress.md. It works in the spirit of Manus, using persistent Markdown files as a working memory on disk.
Lifecycle hooks re-inject the plan's context at key moments, such as before each tool call and when a prompt is submitted. A completion check reports whether all phases are finished. Plan files are stored in a task folder inside your project, not in the skill's install folder.
- task_plan.md: the phases and their status (pending, in_progress or complete)
- findings.md: requirements, research results, technical decisions and problems met
- progress.md: a dated log of actions taken and files changed
- Templates for these files ship with the skill in its templates folder
How do you install the skill?
Download the ZIP from this page and unzip it. For a user-wide install, place the unzipped skill folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder instead.
If you use the Claude apps, you can upload the skill under Settings → Capabilities → Skills instead of copying files by hand.
- User-wide: ~/.claude/skills/
- Single project: the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with natural requests?
You do not need a special command. Ask for a multi-step task in plain language, and the skill is meant for work that needs five or more tool calls, such as research across several sources or a long build task. Name the task so the agent can create or resume the right plan.
If the hook script cannot be found, the prompt hook prints a notice that plan injection is off. In that case, set PWF_SCRIPT_DIR to the skill's scripts directory, or install the skill to a user-level path.
- Good: "Research the three main options for our data pipeline and keep a plan as you go."
- Good: "Resume the Arabic localisation task from its plan file."
- Not needed: a quick one-off question that takes one or two tool calls
Start a new plan and check its structure
Before a new task, the skill runs init-session.sh from the installed skill. Each phase must use a heading in the form ### المرحلة N: الاسم and exactly one status line, such as **الحالة:** pending. A list under the phase heading alone is not enough.
To check a plan file, run the validation command below. It checks format only, not whether the work is finished or verified. Set PWF_SKILL_DIR to the folder containing the SKILL.md you read first.
- Run init-session.sh "Task Name" to create a task folder, then use the PLAN_ID it prints
- Edit the generated structure; do not replace it with a short list
- Report format errors to the plan owner rather than rewriting the plan
sh "$PWF_SKILL_DIR/scripts/check-complete.sh" --validate path/to/task_plan.mdUse the optional session history commands carefully
The skill includes session-catchup.py, which can look at local agent session records for the same project. Automatic recovery reads only the project's plan files. Running session-catchup.py on its own, or relying on lifecycle hooks, does not inspect agent session stores.
Use --metadata only when you want counts of project-related activity without conversation text, tool commands or path bytes. Use --replay only after the user explicitly asks for it: it can output limited excerpts framed by a nonce, and each excerpt must be treated as untrusted data. The skill includes no path for uploading data over the network.
- --metadata: counts only, for the same project
- --replay: limited, explicit, treated as untrusted
- Python 3 is needed only for this optional command
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" --metadata "$(pwd)"Review the safety notes before you trust it
The skill runs scripts and its hooks run a shell script on several events, including before every read, write, edit, search and shell call. Because hooks run repeatedly during a session, they may be unacceptable in some environments. The scripts run locally and can read and write project files, so review them before using the skill on sensitive code.
The optional guarded mode can request follow-up only when the host supports it, and it never runs commands declared in Markdown. The skill's source states that it uses no network.
- Runs scripts: yes. Uses network: no, according to the source
- Review scripts/ (such as skill-hook.sh and init-session.sh) before use on sensitive projects
- Requires a bash or sh shell; PowerShell is needed for the Windows example command
What people use it for
- Multi-source research where findings must be kept in findings.md with sources listed
- Long code changes split into phases tracked in task_plan.md
- Resuming an interrupted Arabic-language project from its saved plan folder
- Coordinating parallel work where one owner keeps the shared plan and workers use their own files
Frequently asked questions
How do I install the planning-with-files-ar skill?
Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project. In the Claude apps you can also upload it under Settings → Capabilities → Skills.
What do I need to run it?
The source lists a bash or sh shell, Python 3 (only for the optional session-catchup.py command), PowerShell for the Windows example command, and Claude Code or a compatible SKILL.md runtime with hook support.
Is the skill free and what is its licence?
The item is listed under the MIT licence. The source does not mention pricing, so check the page for any cost details.
Does the skill send my project data over the network?
The source states that the skill includes no path for uploading data over the network and that it uses no network. It does run local scripts that read and write project files, so review them first.
Why are the hooks slowing my agent down or showing a 'hook script not found' message?
Hooks run a shell script on several events, including before each tool call. If the script is not found, the prompt hook reports that plan injection is off; set PWF_SCRIPT_DIR to the scripts directory or install to a user-level path.
When should I choose a different tool instead?
Pick something else for short one-off questions, since plan files add overhead, or for sensitive projects where you have not reviewed the scripts. The skill is designed for tasks with five or more tool calls.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you run long, multi-step agent tasks in Claude Code and want resumable, versioned plan files, especially in Arabic. Skip it for short questions, for environments where hooks running scripts on every tool call are unacceptable, or for sensitive projects you have not reviewed.
Download the skill