How do I install the File Todos skill?

Run npx skillmds@latest add iliaal/file-todos in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is File Todos safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with File Todos?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is File Todos free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published File Todos?

iliaal (@iliaal) published this skill. Their other Agent Skills are listed on their SkillMD profile.

File Todos by iliaal — Agent Skill

Name: File Todos
Rating: 4.2 (5 reviews)
Author: iliaal

File Todos

File-based todo and task tracking in the todos/ directory. Use when creating, triaging, listing, or managing todo files, tracking work items, managing the backlog, converting PR comments to tracked tasks, or checking todo status and dependencies.

iliaal Updated Sep 10, 2026

File contents

File-based todo tracking

File naming convention

{issue_id}-{status}-{priority}-{description}.md

issue_id: Sequential number (001, 002, 003...) -- never reused
status: pending (needs triage), ready (approved), complete (done)
priority: p1 (critical), p2 (important), p3 (nice-to-have). Mapping from the ia-code-review severity scale: Critical→p1, Important→p2, Medium→p3, Minor→p3.
description: kebab-case, brief description

Examples: 001-pending-p1-mailer-test.md, 002-ready-p1-fix-n-plus-1.md, 005-complete-p2-refactor-csv.md

File Structure

Use todo-template.md as a starting point. YAML frontmatter:

---
status: ready              # pending | ready | complete
priority: p1               # p1 | p2 | p3
issue_id: "002"
tags: [typescript, performance, database]
dependencies: ["001"]      # Issue IDs this is blocked by
---

Required sections: Problem Statement, Findings, Proposed Solutions, Recommended Action, Acceptance Criteria, Work Log

Optional sections: Technical Details, Resources, Notes

Key Distinctions

File-todos system (this skill): Markdown files in todos/ directory for development/project tracking. Used by humans and agents.

Application Todo model: Database model for user-facing task management. Different from this file-based system.

TodoWrite tool: In-memory task tracking during agent sessions. Temporary, not persisted to disk.

Verify

Before considering a todo file correctly written, confirm:

issue_id is unique and sequentially the next number in todos/ (never reused).
All required frontmatter fields are present: status, priority, issue_id.
status and priority values match the filename and their enums (pending|ready|complete, p1|p2|p3).

References

workflows.md - Creating, triaging, dependencies, work logs, completing todos, integration table
quick-reference.md - Bash commands for finding work, dependencies, searching
todo-template.md - Template for new todo files

---name: file-todosclass: tooldescription: >- File-based todo and task tracking in the todos/ directory. Use when creating, triaging, listing, or managing todo files, tracking work items, managing the backlog, converting PR comments to tracked tasks, or checking todo status and dependencies.disable-model-invocation: true---# File-based todo tracking## File naming convention```{issue_id}-{status}-{priority}-{description}.md```- **issue_id**: Sequential number (001, 002, 003...) -- never reused- **status**: `pending` (needs triage), `ready` (approved), `complete` (done)- **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have). Mapping from the `ia-code-review` severity scale: Critical→p1, Important→p2, Medium→p3, Minor→p3.- **description**: kebab-case, brief descriptionExamples: `001-pending-p1-mailer-test.md`, `002-ready-p1-fix-n-plus-1.md`, `005-complete-p2-refactor-csv.md`## File StructureUse [todo-template.md](./assets/todo-template.md) as a starting point. YAML frontmatter:```yaml---status: ready # pending | ready | completepriority: p1 # p1 | p2 | p3issue_id: "002"tags: [typescript, performance, database]dependencies: ["001"] # Issue IDs this is blocked by---```**Required sections:** Problem Statement, Findings, Proposed Solutions, Recommended Action, Acceptance Criteria, Work Log**Optional sections:** Technical Details, Resources, Notes## Key Distinctions**File-todos system (this skill):** Markdown files in `todos/` directory for development/project tracking. Used by humans and agents.**Application Todo model:** Database model for user-facing task management. Different from this file-based system.**TodoWrite tool:** In-memory task tracking during agent sessions. Temporary, not persisted to disk.## VerifyBefore considering a todo file correctly written, confirm:- `issue_id` is unique and sequentially the next number in `todos/` (never reused).- All required frontmatter fields are present: `status`, `priority`, `issue_id`.- `status` and `priority` values match the filename and their enums (`pending|ready|complete`, `p1|p2|p3`).## References- [workflows.md](./references/workflows.md) - Creating, triaging, dependencies, work logs, completing todos, integration table- [quick-reference.md](./references/quick-reference.md) - Bash commands for finding work, dependencies, searching- [todo-template.md](./assets/todo-template.md) - Template for new todo files

Frequently asked questions