file-todos

Manages file-based todo tracking with markdown files, YAML frontmatter, and dependency workflows.

Updated Jan 23, 2026
One-click install
npx skills add https://github.com/stephschofield/beth --skill file-todos-stephschofield
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: file-todos
Source: https://github.com/stephschofield/beth/tree/main/.github/skills/file-todos
Command: npx skills add https://github.com/stephschofield/beth --skill file-todos-stephschofield

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve? Teams lose track of code review findings, technical debt, and feature requests scattered across PR comments and chat threads. This Skill provides a structured, file-based system in a todos/ directory where every work item is a markdown file with YAML frontmatter, making work visible, triageable, and traceable. ## Core Features & Use Cases - Todo Lifecycle Management: Create, triage, and complete todos following a pending → ready → complete status flow with sequential issue IDs and priority levels (p1/p2/p3). - Dependency Tracking: Declare blocking relationships between todos in YAML frontmatter and query them with grep commands to find unblocked work. - Structured Templates: Use the included todo-template.md with required sections (Problem Statement, Findings, Proposed Solutions, Acceptance Criteria, Work Log) for consistent documentation. - Use Case: After a code review surfaces 12 missing test scenarios, create a prioritized todo file with proposed solutions, triage it to ready status, track work sessions in the Work Log, and mark it complete once acceptance criteria pass. ## Quick Start Ask the agent to create a new todo in the todos directory for the performance issue you just found, using the template and assigning it priority p1.

Frequently Asked Questions about file-todos

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a file-based todo for code review findings?▼

Determine the next sequential issue ID, copy the todo template into the todos directory with the naming pattern {id}-{status}-{priority}-{description}.md, then fill in the Problem Statement, Findings, Proposed Solutions, and Acceptance Criteria sections.

How do I track dependencies between todo items in markdown files?▼

Add a dependencies field in the YAML frontmatter listing blocking issue IDs, such as dependencies: ["002", "005"]. Use grep commands like grep -l 'dependencies:.*"002"' todos/*.md to find what a todo blocks.

What is the difference between file-based todos and a database todo model?▼

File-based todos are standalone markdown files in a todos directory used for development and project tracking by humans and agents. A database todo model is a user-facing application feature with Active Record CRUD operations, serving a different purpose.

When should I create a todo instead of fixing an issue immediately?▼

Create a todo when work requires more than 15-20 minutes, needs research or multiple approaches, has dependencies, or requires approval. Act immediately for trivial fixes with complete context and obvious solutions.

How do I triage pending todos to approved status?▼

List pending files with ls todos/*-pending-*.md, review each Problem Statement and Proposed Solutions, then rename approved files from pending to ready, update the frontmatter status, and fill in the Recommended Action section.