Initial release: planning-with-files Claude Code skill

A skill that transforms Claude's workflow to use Manus-style persistent
markdown files for planning, progress tracking, and knowledge storage.

Implements the 3-file pattern (task_plan.md, notes.md, deliverable.md)
inspired by context engineering principles.
This commit is contained in:
OthmanAdi
2026-01-03 08:30:28 +01:00
commit 1f54991325
6 changed files with 678 additions and 0 deletions
+19
View File
@@ -0,0 +1,19 @@
# OS files
.DS_Store
Thumbs.db
# Editor files
*.swp
*.swo
*~
.vscode/
.idea/
# Development planning files (meta: I used this skill to build this skill!)
task_plan.md
research_notes.md
notes.md
# Keep the skill folder clean
*.log
*.tmp
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Ahmad Adi
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+166
View File
@@ -0,0 +1,166 @@
# Planning with Files
> **Work like Manus** — the AI agent company Meta just acquired for **$2 billion**.
A Claude Code skill that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-blue)](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills)
---
## Why This Skill?
On December 29, 2025, [Meta acquired Manus for $2 billion](https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/). In just 8 months, Manus went from launch to $100M+ revenue. Their secret? **Context engineering**.
This skill implements Manus's core workflow pattern:
> "Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables."
> — Manus AI
## The Problem
Claude Code (and most AI agents) suffer from:
- **Volatile memory** — TodoWrite tool disappears on context reset
- **Goal drift** — After 50+ tool calls, original goals get forgotten
- **Hidden errors** — Failures aren't tracked, so the same mistakes repeat
- **Context stuffing** — Everything crammed into context instead of stored
## The Solution: 3-File Pattern
For every complex task, create THREE files:
```
task_plan.md → Track phases and progress
notes.md → Store research and findings
[deliverable].md → Final output
```
### The Loop
```
1. Create task_plan.md with goal and phases
2. Research → save to notes.md → update task_plan.md
3. Read notes.md → create deliverable → update task_plan.md
4. Deliver final output
```
**Key insight:** By reading `task_plan.md` before each decision, goals stay in the attention window. This is how Manus handles ~50 tool calls without losing track.
## Installation
### Option 1: Clone directly (Recommended)
```bash
# Navigate to your Claude Code skills directory
cd ~/.claude/skills # or your custom skills path
# Clone this skill
git clone https://github.com/OthmanAdi/planning-with-files.git
```
### Option 2: Manual installation
1. Download or copy the `planning-with-files` folder
2. Place it in your Claude Code skills directory:
- macOS/Linux: `~/.claude/skills/`
- Windows: `%USERPROFILE%\.claude\skills\`
### Verify Installation
In Claude Code, the skill will automatically activate when you:
- Start complex tasks
- Mention "planning", "organize", or "track progress"
- Ask for structured work
## Usage
Once installed, Claude will automatically:
1. **Create `task_plan.md`** before starting complex tasks
2. **Update progress** with checkboxes after each phase
3. **Store findings** in `notes.md` instead of stuffing context
4. **Log errors** for future reference
5. **Re-read plan** before major decisions
### Example
**You:** "Research the benefits of TypeScript and write a summary"
**Claude creates:**
```markdown
# Task Plan: TypeScript Benefits Research
## Goal
Create a research summary on TypeScript benefits.
## Phases
- [x] Phase 1: Create plan ✓
- [ ] Phase 2: Research and gather sources (CURRENT)
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary
## Status
**Currently in Phase 2** - Searching for sources
```
Then continues through each phase, updating the file as it goes.
## The Manus Principles
This skill implements these key context engineering principles:
| Principle | Implementation |
|-----------|----------------|
| Filesystem as memory | Store in files, not context |
| Attention manipulation | Re-read plan before decisions |
| Error persistence | Log failures in plan file |
| Goal tracking | Checkboxes show progress |
| Append-only context | Never modify history |
## File Structure
```
planning-with-files/
├── SKILL.md # Core instructions (what Claude reads)
├── reference.md # Manus principles deep dive
├── examples.md # Real usage examples
└── README.md # This file
```
## When to Use
**Use this pattern for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Acknowledgments
- **Manus AI** — For pioneering context engineering patterns that made this possible
- **Anthropic** — For Claude Code and the Agent Skills framework
- Based on [Context Engineering for AI Agents](https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
## License
MIT License — feel free to use, modify, and distribute.
---
**Author:** [Ahmad Othman Ammar Adi](https://github.com/OthmanAdi)
+160
View File
@@ -0,0 +1,160 @@
---
name: planning-with-files
description: Transforms workflow to use Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when the user mentions planning, organizing work, tracking progress, or wants structured output.
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** in the working directory
2. **Define phases** with checkboxes
3. **Update after each phase** - mark [x] and change status
4. **Read before deciding** - refresh goals in attention window
## The 3-File Pattern
For every non-trivial task, create THREE files:
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Track phases and progress | After each phase |
| `notes.md` | Store findings and research | During research |
| `[deliverable].md` | Final output | At completion |
## Core Workflow
```
Loop 1: Create task_plan.md with goal and phases
Loop 2: Research → save to notes.md → update task_plan.md
Loop 3: Read notes.md → create deliverable → update task_plan.md
Loop 4: Deliver final output
```
### The Loop in Detail
**Before each major action:**
```bash
Read task_plan.md # Refresh goals in attention window
```
**After each phase:**
```bash
Edit task_plan.md # Mark [x], update status
```
**When storing information:**
```bash
Write notes.md # Don't stuff context, store in file
```
## task_plan.md Template
Create this file FIRST for any complex task:
```markdown
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Phases
- [ ] Phase 1: Plan and setup
- [ ] Phase 2: Research/gather information
- [ ] Phase 3: Execute/build
- [ ] Phase 4: Review and deliver
## Key Questions
1. [Question to answer]
2. [Question to answer]
## Decisions Made
- [Decision]: [Rationale]
## Errors Encountered
- [Error]: [Resolution]
## Status
**Currently in Phase X** - [What I'm doing now]
```
## notes.md Template
For research and findings:
```markdown
# Notes: [Topic]
## Sources
### Source 1: [Name]
- URL: [link]
- Key points:
- [Finding]
- [Finding]
## Synthesized Findings
### [Category]
- [Finding]
- [Finding]
```
## Critical Rules
### 1. ALWAYS Create Plan First
Never start a complex task without `task_plan.md`. This is non-negotiable.
### 2. Read Before Decide
Before any major decision, read the plan file. This keeps goals in your attention window.
### 3. Update After Act
After completing any phase, immediately update the plan file:
- Mark completed phases with [x]
- Update the Status section
- Log any errors encountered
### 4. Store, Don't Stuff
Large outputs go to files, not context. Keep only paths in working memory.
### 5. Log All Errors
Every error goes in the "Errors Encountered" section. This builds knowledge for future tasks.
## When to Use This Pattern
**Use 3-file pattern for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating something
- Tasks spanning multiple tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Anti-Patterns to Avoid
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create `task_plan.md` file |
| State goals once and forget | Re-read plan before each decision |
| Hide errors and retry | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
## Advanced Patterns
See [reference.md](reference.md) for:
- Attention manipulation techniques
- Error recovery patterns
- Context optimization from Manus
See [examples.md](examples.md) for:
- Real task examples
- Complex workflow patterns
+202
View File
@@ -0,0 +1,202 @@
# Examples: Planning with Files in Action
## Example 1: Research Task
**User Request:** "Research the benefits of morning exercise and write a summary"
### Loop 1: Create Plan
```bash
Write task_plan.md
```
```markdown
# Task Plan: Morning Exercise Benefits Research
## Goal
Create a research summary on the benefits of morning exercise.
## Phases
- [ ] Phase 1: Create this plan ✓
- [ ] Phase 2: Search and gather sources
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary
## Key Questions
1. What are the physical health benefits?
2. What are the mental health benefits?
3. What scientific studies support this?
## Status
**Currently in Phase 1** - Creating plan
```
### Loop 2: Research
```bash
Read task_plan.md # Refresh goals
WebSearch "morning exercise benefits"
Write notes.md # Store findings
Edit task_plan.md # Mark Phase 2 complete
```
### Loop 3: Synthesize
```bash
Read task_plan.md # Refresh goals
Read notes.md # Get findings
Write morning_exercise_summary.md
Edit task_plan.md # Mark Phase 3 complete
```
### Loop 4: Deliver
```bash
Read task_plan.md # Verify complete
Deliver morning_exercise_summary.md
```
---
## Example 2: Bug Fix Task
**User Request:** "Fix the login bug in the authentication module"
### task_plan.md
```markdown
# Task Plan: Fix Login Bug
## Goal
Identify and fix the bug preventing successful login.
## Phases
- [x] Phase 1: Understand the bug report ✓
- [x] Phase 2: Locate relevant code ✓
- [ ] Phase 3: Identify root cause (CURRENT)
- [ ] Phase 4: Implement fix
- [ ] Phase 5: Test and verify
## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?
## Decisions Made
- Auth handler is in src/auth/login.ts
- Error occurs in validateToken() function
## Errors Encountered
- [Initial] TypeError: Cannot read property 'token' of undefined
→ Root cause: user object not awaited properly
## Status
**Currently in Phase 3** - Found root cause, preparing fix
```
---
## Example 3: Feature Development
**User Request:** "Add a dark mode toggle to the settings page"
### The 3-File Pattern in Action
**task_plan.md:**
```markdown
# Task Plan: Dark Mode Toggle
## Goal
Add functional dark mode toggle to settings.
## Phases
- [x] Phase 1: Research existing theme system ✓
- [x] Phase 2: Design implementation approach ✓
- [ ] Phase 3: Implement toggle component (CURRENT)
- [ ] Phase 4: Add theme switching logic
- [ ] Phase 5: Test and polish
## Decisions Made
- Using CSS custom properties for theme
- Storing preference in localStorage
- Toggle component in SettingsPage.tsx
## Status
**Currently in Phase 3** - Building toggle component
```
**notes.md:**
```markdown
# Notes: Dark Mode Implementation
## Existing Theme System
- Located in: src/styles/theme.ts
- Uses: CSS custom properties
- Current themes: light only
## Files to Modify
1. src/styles/theme.ts - Add dark theme colors
2. src/components/SettingsPage.tsx - Add toggle
3. src/hooks/useTheme.ts - Create new hook
4. src/App.tsx - Wrap with ThemeProvider
## Color Decisions
- Dark background: #1a1a2e
- Dark surface: #16213e
- Dark text: #eaeaea
```
**dark_mode_implementation.md:** (deliverable)
```markdown
# Dark Mode Implementation
## Changes Made
### 1. Added dark theme colors
File: src/styles/theme.ts
...
### 2. Created useTheme hook
File: src/hooks/useTheme.ts
...
```
---
## Example 4: Error Recovery Pattern
When something fails, DON'T hide it:
### Before (Wrong)
```
Action: Read config.json
Error: File not found
Action: Read config.json # Silent retry
Action: Read config.json # Another retry
```
### After (Correct)
```
Action: Read config.json
Error: File not found
# Update task_plan.md:
## Errors Encountered
- config.json not found → Will create default config
Action: Write config.json (default config)
Action: Read config.json
Success!
```
---
## The Read-Before-Decide Pattern
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
+110
View File
@@ -0,0 +1,110 @@
# Reference: Manus Context Engineering Principles
This skill is based on the context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### 1. Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**Problem:** Context windows have limits. Stuffing everything in context degrades performance and increases costs.
**Solution:** Treat the filesystem as unlimited memory:
- Store large content in files
- Keep only paths in context
- Agent can "look up" information when needed
- Compression must be REVERSIBLE
### 2. Attention Manipulation Through Repetition
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Keep a `task_plan.md` file that gets RE-READ throughout execution:
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
By reading the plan file before each decision, goals appear in the attention window.
### 3. Keep Failure Traces
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
**Problem:** Instinct says hide errors, retry silently. This wastes tokens and loses learning.
**Solution:** KEEP failed actions in the plan file:
```markdown
## Errors Encountered
- [2025-01-03] FileNotFoundError: config.json not found → Created default config
- [2025-01-03] API timeout → Retried with exponential backoff, succeeded
```
The model updates its internal understanding when seeing failures.
### 4. Avoid Few-Shot Overfitting
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
### 5. Stable Prefixes for Cache Optimization
**Problem:** Agents are input-heavy (100:1 ratio). Every token costs money.
**Solution:** Structure for cache hits:
- Put static content FIRST
- Append-only context (never modify history)
- Consistent serialization
### 6. Append-Only Context
**Problem:** Modifying previous messages invalidates KV-cache.
**Solution:** NEVER modify previous messages. Always append new information.
## The Agent Loop
Manus operates in a continuous loop:
```
1. Analyze → 2. Think → 3. Select Tool → 4. Execute → 5. Observe → 6. Iterate → 7. Deliver
```
### File Operations in the Loop:
| Operation | When to Use |
|-----------|-------------|
| `write` | New files or complete rewrites |
| `append` | Adding sections incrementally |
| `edit` | Updating specific parts (checkboxes, status) |
| `read` | Reviewing before decisions |
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
## Key Quotes
> "If the model improvement is the rising tide, we want Manus to be the boat, not the piling stuck on the seafloor."
> "For complex tasks, I save notes, code, and findings to files so I can reference them as I work."
> "I used file.edit to update checkboxes in my plan as I progressed, rather than rewriting the whole file."
## Source
Based on Manus's official context engineering documentation:
https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus