xiaohongshu
xiaohongshu
artifact-tracking
Use this skill when creating, updating, or querying AI-optimized tracking artifacts (progress files, context notes, bug fixes, observation logs) in YAML+Markdown hybrid format for 95% token reduction. Invoke for: creating phase progress tracking, updating task status and blockers, querying pendin...
Full skill instructions
Create, update, query, and validate AI-optimized tracking artifacts with 95% token efficiency.
Traditional tracking artifacts (pure markdown) waste tokens:
This skill provides a hybrid YAML+Markdown format optimized for AI agent consumption:
Starting a new phase of implementation? Create a phase progress file with structured task list, success criteria, and blockers.
Example: "Create Phase 2 progress tracking for authentication-overhaul PRD"
Need to mark a task complete, move it to in-progress, or block it? Surgical field-level updates without full-file rewrites.
Example: "Update TASK-003 status to 'in_progress' and add blocker reference"
Need to find all pending tasks for a specific agent? Or all blockers across phases? Query with filters.
Example: "Show all blocked tasks in advanced-editing-v2 phases 1-3"
Discovered important technical decisions or gotchas? Document them in structured context files for future reference.
Example: "Record Phase 1 implementation decisions and integration patterns in context file"
Handing off work to another agent or session? Get a concise summary of pending tasks, blockers, and next actions.
Example: "Generate session handoff for frontend-developer to continue Phase 3"
Before phase completion, verify tracking files are complete, consistent, and accurate.
Example: "Validate Phase 2 progress file for schema compliance and metric accuracy"
Have old markdown progress files? Convert them to hybrid format with Python migration tool.
Example: "Migrate legacy progress files to hybrid YAML+Markdown format"
Task("artifact-tracker", "Create progress tracking for Phase 2 of listings-enhancements-v3 PRD. Include 5 main tasks: implement search API, add filtering UI, optimize database query, write tests, and documentation. Mark all as pending status.")
This will create .claude/progress/listings-enhancements-v3/phase-2-progress.md with structured YAML metadata and task list.
Task("artifact-tracker", "Update phase-2-progress.md for advanced-editing-v2: Mark TASK-1.5 (React modal optimization) as 'in_progress' and update overall progress to 40%")
YAML metadata is updated surgically without touching task descriptions or other sections.
Task("artifact-query", "Find all blocked tasks in blocks-v2-implementation phases 1-3. Show task ID, description, blocker reason, and assigned agent")
Returns structured results filtered by status across multiple files.
Task("artifact-query", "Generate session handoff for ui-engineer-enhanced continuing Phase 4 of advanced-editing-v2. Include pending tasks, current blockers, next session agenda, and architecture context")
Concise summary with all info needed to continue work.
Task("artifact-validator", "Validate Phase 1 and Phase 2 progress files for prompt-card-v1. Check schema compliance, metric accuracy, and link validity")
Automated quality checks before phase completion.
When: Starting implementation of a new phase from PRD
Steps:
artifact-tracker agent.claude/progress/[prd-name]/phase-[N]-progress.mdResult: Structured file that can be queried and updated efficiently across sessions
When: Task completes, enters work, gets blocked, or becomes at-risk
Steps:
artifact-tracker agentResult: Minimal token usage (~1KB update vs ~25KB full-file approach)
When: Need to find tasks by criteria (agent, status, priority, blocker status)
Steps:
artifact-query agentResult: Seconds to answer queries that would take minutes reading full files
When: Phase nearing completion, want to ensure tracking is accurate
Steps:
artifact-validator agentResult: High-confidence phase completion tracking
When: Have old markdown progress files to update to new format
Steps:
python scripts/convert_to_hybrid.py path/to/old/file.mdResult: Bulk migration without manual rewriting
Creates and updates progress files with field-level precision. Specializes in:
Use when: Creating or updating tracking files, recording decisions
Queries and synthesizes tracking artifacts efficiently. Specializes in:
Use when: Finding information, generating reports, creating handoffs
Validates and maintains artifact quality. Specializes in:
Use when: Validating files, checking quality, finding/fixing issues
Tracking artifacts use hybrid YAML+Markdown format:
---
# Machine-readable metadata (YAML frontmatter)
type: progress
prd: "listings-enhancements-v3"
phase: 2
title: "Search and Filtering Implementation"
status: in_progress
progress: 45
total_tasks: 8
completed_tasks: 3
in_progress_tasks: 2
blocked_tasks: 1
created: 2025-11-15
updated: 2025-11-17
owners: ["ui-engineer-enhanced"]
contributors: ["backend-engineer"]
blockers:
- id: "BLOCKER-001"
title: "Missing API endpoint"
severity: "critical"
blocking: ["TASK-2.3", "TASK-2.4"]
resolution: "Awaiting backend-engineer implementation"
---
# Listings Enhancements V3 - Phase 2: Search and Filtering
**Phase**: 2 of 4
**Status**: In Progress (45% complete)
**Owner**: ui-engineer-enhanced
## Tasks
| ID | Task | Status | Agent | Notes |
|----|------|--------|-------|-------|
| TASK-2.1 | API search endpoint | ✓ | backend-engineer | Complete |
| TASK-2.2 | Search UI component | 🔄 | ui-engineer-enhanced | In review |
| TASK-2.3 | Filter dropdown | 🚫 | ui-engineer-enhanced | Blocked by BLOCKER-001 |
| ... | ... | ... | ... | ... |
## Architecture Context
[Narrative markdown content about implementation decisions, patterns, gotchas]
---
**Key**: YAML frontmatter is machine-readable metadata. Markdown body is human-readable narrative.
See ./format-specification.md for complete format documentation with all YAML fields, value types, and validation rules.
Progress and context tracking follows ONE-per-phase rule:
.claude/
├── progress/
│ └── [prd-name]/
│ ├── phase-1-progress.md # ONE per phase
│ ├── phase-2-progress.md
│ └── phase-3-progress.md
│
└── worknotes/
├── [prd-name]/
│ ├── phase-1-context.md # ONE per phase
│ ├── phase-2-context.md
│ └── phase-3-context.md
│
├── fixes/
│ └── bug-fixes-tracking-11-25.md # Monthly tracking
│
└── observations/
└── observation-log-11-25.md # Monthly observations
Python utilities in ./scripts/ for programmatic operations:
Migrate old markdown files to hybrid YAML+Markdown format:
python scripts/convert_to_hybrid.py /path/to/old/progress.md
# Output: progress_hybrid.md (converted format)
Validate tracking files against schema:
python scripts/validate_artifact.py /path/to/progress.md
# Output: validation report with issues and recommendations
Query tracking files programmatically:
python scripts/query_artifacts.py \
--prd "listings-enhancements-v3" \
--status "blocked" \
--phase 2
# Output: JSON of matching tasks
Bulk migration of all legacy files:
python scripts/migrate_all.py /path/to/legacy/dir
# Output: Migrated files in hybrid format
See ./scripts/README.md for complete documentation.
Traditional Approach:
Artifact-Tracking Approach:
Savings: 474KB (~142,200 tokens) 98.75% reduction
Traditional Approach:
Artifact-Tracking Approach:
Savings: 813KB (~243,900 tokens) 97.1% reduction
Task("artifact-tracker", "Create Phase 1 progress tracking for blocks-v2-implementation PRD. Phase title: 'Core Blocks Model Implementation'. Include these tasks: implement Block model schema, add database migrations, create block repository layer, add CRUD endpoints, write integration tests. All tasks start as pending with medium priority. Assign to backend-engineer.")
Result: .claude/progress/blocks-v2-implementation/phase-1-progress.md created with structured YAML metadata and task list.
Task("artifact-tracker", "Update phase-1-progress.md for advanced-editing-v2: Mark TASK-1.1 (Modal component skeleton) as complete. Mark TASK-1.2 (Form inputs integration) as in_progress. Update overall progress from 20% to 35%. Add note: 'UI skeleton complete, working on form integration'")
Result: YAML metadata updated surgically, progress metrics recalculated.
Task("artifact-query", "Find all critical and high-severity blockers across all phases of prompt-card-v1 PRD. Show blocker ID, title, what tasks it's blocking, and resolution path.")
Result: Structured list of blockers with impact analysis.
Task("artifact-query", "Generate session handoff for ai-artifacts-engineer continuing work on listings-enhancements-v3. Show: current phase, pending tasks in priority order, active blockers, implementation decisions from context files, and immediate next actions for new session.")
Result: Concise handoff with all context needed to continue.
Never create multiple progress files for the same phase. Use a single .claude/progress/[prd]/phase-[N]-progress.md and update it across sessions.
Keep YAML frontmatter current:
progress: Update as tasks completeupdated: Set when making changesblockers: Add/remove as situation changescompleted_tasks, in_progress_tasks: Keep in sync with markdown tasksTask IDs should follow pattern: TASK-[PHASE].[SEQUENCE] (e.g., TASK-2.1, TASK-2.2, TASK-2.3)
When a task is blocked, reference the blocker ID:
Blocked by BLOCKER-001blockers.blocking array: ["TASK-2.3", "TASK-2.4"]Never read entire progress files manually when querying. Use artifact-query agent:
Use artifact-validator to clean up after phase completion:
status: completeComplete Format Specification: See ./format-specification.md for all YAML fields, value types, constraints, and validation rules.
Migration Guide: See ./migration-guide.md for step-by-step instructions to convert existing markdown artifacts to hybrid format.
Query Patterns: See ./query-patterns.md for common query examples and efficient filter combinations.
Template Reference: See ./TEMPLATES-INDEX.md for all available templates (progress, context, bug fixes, observations).
Schema Reference: See ./schemas/ directory for validation schemas and examples.
This skill works with:
When starting a new PRD:
xiaohongshu
technical spec
product ux expert
database patterns
Conduct multi-agent task orchestration and workflow coordination.
Initialize project with Conductor artifacts (product definition,
Expert in web animations, transitions, and motion design using Framer Motion and CSS
Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...
PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.
Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...
Display project status, active tracks, and next actions
Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.
Generate, edit, and beat-sync AI video with leading models in one workspace.
The world's fastest calendar for remote work
Transform Your Design with AI Designer by ImgCreator.ai
Revolutionizing Video Production with AI-Powered Creativity
Extend an image past the frame and let AI fill the new aspect ratio.
Discover your celebrity doppelgänger with StarByFace!
ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.
Opus.ai: Revolutionize Your Web Experience