AGENT SKILL

file-todos

This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.

License 许可
MIT
最近更新
2026-11-06
Stars
★ 4
Forks
0

01 前言 Front Matter

name
file-todos
description
This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
user-invocable
true

02 资源文件 1

03 SKILL.md 正文

File-Based Todo Tracking Skill

Overview

The todos/ directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.

This skill should be used when:

  • Creating new todos from findings or feedback
  • Managing todo lifecycle (pending → ready → complete)
  • Triaging pending items for approval
  • Checking or managing dependencies
  • Converting PR comments or code findings into tracked work
  • Updating work logs during todo execution

File Naming Convention

Todo files follow this naming pattern:

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

Components:

  • 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)
  • 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

Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at todo-template.md as a starting point when creating new todos.

Required sections:

  • Problem Statement - What is broken, missing, or needs improvement?
  • Findings - Investigation results, root cause, key discoveries
  • Proposed Solutions - Multiple options with pros/cons, effort, risk
  • Recommended Action - Clear plan (filled during triage)
  • Acceptance Criteria - Testable checklist items
  • Work Log - Chronological record with date, actions, learnings

Optional sections:

  • Technical Details - Affected files, related components, DB changes
  • Resources - Links to errors, tests, PRs, documentation
  • Notes - Additional context or decisions

YAML frontmatter fields:

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

Common Workflows

Creating a New Todo

To create a new todo from findings or feedback:

  1. Determine next issue ID: ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1
  2. Copy template: cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md
  3. Edit and fill required sections:
    • Problem Statement
    • Findings (if from investigation)
    • Proposed Solutions (multiple options)
    • Acceptance Criteria
    • Add initial Work Log entry
  4. Determine status: pending (needs triage) or ready (pre-approved)
  5. Add relevant tags for filtering

When to create a todo:

  • Requires more than 15-20 minutes of work
  • Needs research, planning, or multiple approaches considered
  • Has dependencies on other work
  • Requires manager approval or prioritization
  • Part of larger feature or refactor
  • Technical debt needing documentation

When to act immediately instead:

  • Issue is trivial (< 15 minutes)
  • Complete context available now
  • No planning needed
  • User explicitly requests immediate action
  • Simple bug fix with obvious solution

Triaging Pending Items

To triage pending todos:

  1. List pending items: ls todos/*-pending-*.md
  2. For each todo:
    • Read Problem Statement and Findings
    • Review Proposed Solutions
    • Make decision: approve, defer, or modify priority
  3. Update approved todos:
    • Rename file: mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md
    • Update frontmatter: status: pending → status: ready
    • Fill "Recommended Action" section with clear plan
    • Adjust priority if different from initial assessment
  4. Deferred todos stay in pending status

Use slash command: /triage for interactive approval workflow

Managing Dependencies

To track dependencies:

dependencies: ["002", "005"]  # This todo blocked by issues 002 and 005
dependencies: []               # No blockers - can work immediately

To check what blocks a todo:

grep "^dependencies:" todos/003-*.md

To find what a todo blocks:

grep -l 'dependencies:.*"002"' todos/*.md

To verify blockers are complete before starting:

for dep in 001 002 003; do
  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
done

Updating Work Logs

When working on a todo, always add a work log entry:

### YYYY-MM-DD - Session Title

**By:** Claude Code / Developer Name

**Actions:**
- Specific changes made (include file:line references)
- Commands executed
- Tests run
- Results of investigation

**Learnings:**
- What worked / what didn't
- Patterns discovered
- Key insights for future work

Work logs serve as:

  • Historical record of investigation
  • Documentation of approaches attempted
  • Knowledge sharing for team
  • Context for future similar work

Completing a Todo

To mark a todo as complete:

  1. Verify all acceptance criteria checked off
  2. Update Work Log with final session and results
  3. Rename file: mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md
  4. Update frontmatter: status: ready → status: complete
  5. Check for unblocked work: grep -l 'dependencies:.*"002"' todos/*-ready-*.md
  6. Commit with issue reference: feat: resolve issue 002

Integration with Development Workflows

Trigger Flow Tool
Code review /workflows:review → Findings → /triage → Todos Review agent + skill
PR comments /resolve_pr_parallel → Individual fixes → Todos gh CLI + skill
Code TODOs /resolve_todo_parallel → Fixes + Complex todos Agent + skill
Planning Brainstorm → Create todo → Work → Complete Skill
Feedback Discussion → Create todo → Triage → Work Skill + slash

Quick Reference Commands

Finding work:

# List highest priority unblocked work
grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md

# List all pending items needing triage
ls todos/*-pending-*.md

# Find next issue ID
ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", \$1+1}'

# Count by status
for status in pending ready complete; do
  echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)"
done

Dependency management:

# What blocks this todo?
grep "^dependencies:" todos/003-*.md

# What does this todo block?
grep -l 'dependencies:.*"002"' todos/*.md

Searching:

# Search by tag
grep -l "tags:.*rails" todos/*.md

# Search by priority
ls todos/*-p1-*.md

# Full-text search
grep -r "payment" todos/

Key Distinctions

File-todos system (this skill):

  • Markdown files in todos/ directory
  • Development/project tracking
  • Standalone markdown files with YAML frontmatter
  • Used by humans and agents

Rails Todo model:

  • Database model in app/models/todo.rb
  • User-facing feature in the application
  • Active Record CRUD operations
  • Different from this file-based system

TodoWrite tool:

  • In-memory task tracking during agent sessions
  • Temporary tracking for single conversation
  • Not persisted to disk
  • Different from both systems above

04 同仓库更多 Skills

barkleesanders
barkleesanders/claude-code-starter

zi-search

暂无简介

★ 4
barkleesanders
barkleesanders/claude-code-starter

visualise

Render inline interactive visuals — SVG diagrams, HTML widgets, charts, and explainers — directly in the conversation. Use this skill whenever the user asks to visualize, diagram, chart, illustrate, or explain something visually, or when an explanation would genuinely benefit from a spatial/interactive diagram rather than text. Also triggers for: flowcharts, architecture diagrams, data visualizations, interactive explainers, comparison layouts, UI mockups, and any request containing 'show me', 'draw', 'map out', 'visualize', or 'diagram'. Even when the user doesn't explicitly ask for a visual, use this skill proactively when the topic has spatial, sequential, or systemic relationships that a diagram would clarify better than prose.

★ 4
barkleesanders
barkleesanders/claude-code-starter

video

When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Runway,' 'Kling,' 'Pika,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social-content. For paid video ad creative, see ad-creative.

★ 4
barkleesanders
barkleesanders/claude-code-starter

manim-video

Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.

★ 4
barkleesanders
barkleesanders/claude-code-starter

video-use

Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.

★ 4
barkleesanders
barkleesanders/claude-code-starter

ui-improver

暂无简介

★ 4