Agent-Skills.md

Agent Skills: .aiwork Folder Protocol

Structure AI work artifacts under .aiwork/{YYYY-MM-DD}_{slug}/ folders using the project's protocol (triage, research, spec, prd, plan, review, notes, docs/). Use when the user asks to plan, make a spec, triage, research a task, write a report, code review, summarize findings, save the work, document decisions, record this, write that down, persist findings, or references any path under .aiwork/. Also use when starting a non-trivial task that needs a plan or spec before implementation, or when finishing one and capturing notes.

UncategorizedID: lttr/claude-marketplace/aiwork-protocol

Repository

lttr/claude-marketplace
lttrLicense: MIT
21

Install this agent skill to your local

pnpm dlx add-skill https://github.com/lttr/claude-marketplace/tree/HEAD/plugins/aiwork/skills/aiwork-protocol

Skill Files

Browse the full folder contents for aiwork-protocol.

Download Skill

Loading file tree…

plugins/aiwork/skills/aiwork-protocol/SKILL.md

Skill Metadata

Name
aiwork-protocol
Description
Structure AI work artifacts under .aiwork/{YYYY-MM-DD}_{slug}/ folders using the project's protocol (triage, research, spec, prd, plan, review, notes, docs/). Use when the user asks to plan, make a spec, triage, research a task, write a report, code review, summarize findings, save the work, document decisions, record this, write that down, persist findings, or references any path under .aiwork/. Also use when starting a non-trivial task that needs a plan or spec before implementation, or when finishing one and capturing notes.

.aiwork Folder Protocol

Repository-local folder for AI work artifacts, organized by feature or task. Artifacts structure thinking in-session and provide context for future sessions when referenced manually.

Folder layout

.aiwork/
  2026-01-27_auth-refactor/
    triage.md
    spec.md
  • Folder: {YYYY-MM-DD}_{slug}/, slug lowercase kebab-case, max 40 chars.
  • File: {type}.md. Numbering for multiples of same type:
    • plan.md → plan_2.md → plan_3.md — when one plan was expected, more followed.
    • plan_1.md → plan_2.md → plan_3.md — when multiple are expected from the start.
    • Don't mix schemes in one folder.
  • Multi-day: optionally prefix filenames with {YYYY-MM-DD}_.

Usually 1-2 artifacts per task. Pick types that fit.

Grouping and restructuring

One task = one folder. Drift signals:

  • Two folders with overlapping scope or near-identical slugs
  • Cross-folder references: / "Source plan: ../..." pointers
  • Folder that exists only because a ticket number arrived mid-task

On drift, propose consolidation: move artifacts into the canonical folder with a superseded_by: pointer, or merge under one date. Ask before moving files.

Artifact types (all optional)

  • triage — problem framing, what's known
  • research — codebase exploration, doc reading
  • prd — product requirements, success criteria
  • spec — technical/architecture decisions
  • plan — actionable implementation steps
  • review — code review report
  • notes — findings, decisions from implementation
  • implementation-notes — chronological log kept by /implement: workflow events (ticket started/done, chain stopped) plus decisions, deviations, open questions
  • tickets/ — subfolder of vertical-slice tickets, one file per ticket (NN_slug.md, numbered in dependency order), status + blocked_by in frontmatter; created by /to-tickets, worked by /implement
  • docs/ — subfolder for downloaded external docs

Custom types (cascade-map.md, checklist.md) are fine when they fit better.

Division of labor with triage: both skills trigger on the word "triage". aiwork-protocol decides where the artifact lands; triage decides what goes in it. Producing the report content is triage's job — this skill only names and places the file.

When to create a new plan

New plan file when the approach changes or new constraints emerge between iterations. Otherwise continue the previous plan — don't start one just because the session is new.

Frontmatter

Folder date + filename already encode creation time and type, so don't duplicate. Add structured data that's useful for the artifact.

---
ticket: #123456
references:
  - "Parent: #38234"
  - https://docs.example.com/auth
story_points: 8
superseded_by: plan_2.md
---

Common fields: ticket, references, superseded_by. Avoid fields that need manual upkeep across sessions.

Version control

Whether to commit .aiwork/ is up to the project — either traceability or ephemeral working artifacts is fine.