project-knowledge-harness
Set up a structured project memory for any software project — TODO.md as priority/effort-tagged index of future work, backlog/ for resume-friendly research/design notes on P? items, and pitfalls/ as a symptom-grep-able knowledge base of past traps. Use when a user wants somewhere to record "maybe later" ideas, freeze troubleshooting state, capture trade-off analysis, or stop re-debugging the same problem.
How do I install this agent skill?
npx skills add https://github.com/daviddwlee84/agent-skills --skill project-knowledge-harnessIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a set of shell scripts for managing project metadata, including TODO lists, research backlogs, and debugging pitfalls. It operates entirely on local files within the project repository and does not perform any network operations or access sensitive system data.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
project-knowledge-harness
A lightweight, file-based memory harness for any software project.
Three surfaces, sharply separated by time direction and access pattern:
| Surface | Time | Question it answers | Access pattern |
|---|---|---|---|
TODO.md | Future | "What might we do later?" | Read top to bottom (priority lanes) |
backlog/<slug>.md | Future | "What was the analysis behind this idea?" | Indexed from TODO.md |
pitfalls/<slug>.md | Past | "I see error X — has this happened before?" | Grep symptom keywords |
Plus, in projects that already have agent contracts, AGENTS.md Hard
invariants answer "What rules MUST agents follow?". Pitfalls graduate to
Hard invariants when serious enough — see
references/when-to-add-docs.md.
When to use this skill
Use this skill when the user surfaces any of:
- A long-term TODO list with no home, or a messy
TODO.mdthat needs structure (signals: "where should ideas go?", "maybe later", "工程量太大需要再評估") - A debugging session worth saving (signals: "keep solving the same problem twice", "save this troubleshooting", "踩過的坑", "TROUBLESHOOTING.md scattered across docs/")
- A request to consolidate
IDEAS.md/ROADMAP.md/WISHLIST.md/LESSONS.mdfiles
Do NOT use this skill for active sprint planning (use issue trackers, or
td for in-flight agent work — see "Optional: td integration" below),
ephemeral agent scratchpads (use .claude/plans/), or current feature
documentation (use docs/).
How to apply this skill (default workflow)
The skill bundles six scripts and several templates. Default to the
init script for setup, and default to add-todo.sh / sweep-inbox.sh
for capture rather than asking the agent to edit TODO.md by hand.
scripts/
init.sh # one-shot setup of TODO.md + backlog/ + pitfalls/
# + agent guidance + README snippet
todo-kanban.sh # validate TODO.md format and render kanban-style board
add-todo.sh # insert a structured entry into the right ## P* lane
promote-todo.sh # move an active TODO item to ## Done with the right syntax
sweep-inbox.sh # triage backlog/inbox.md into TODO.md via add-todo.sh
start-todo.sh # optional: open/reuse a td issue for an item (no-op without td)
_lib/ # shared TODO parser + td bridge (sourced, not run directly)
1. Run scripts/init.sh against the target repo
scripts/init.sh \
--target /path/to/project \
--project-name "My Project" \
--deployment chezmoi # or npm | pip | docker | none
The script:
- Creates
TODO.md,backlog/README.md,pitfalls/README.mdfromassets/*.template, substituting placeholders. - Appends an agent-guidance snippet to
AGENTS.md/CLAUDE.md(auto-detected, override with--agent-contract). - Appends a "Roadmap & lessons learned" section to
README.md. - Runs
scripts/todo-kanban.sh --validate-only TODO.mdso any drift is caught immediately. - Prints the deployment-exclusion lines you should add manually (it does
not edit ignore files — see
references/deployment-exclusion.md).
init.sh is idempotent: existing files are skipped unless --force is
given, and snippets append only if a sentinel marker is missing.
2. Mid-conversation, when the user surfaces a "maybe later" idea
Signals: "maybe later", "nice to have", "if I'm interested", "工程量太大需要再評估", "先記下來", "not now but…".
-
If
TODO.mddoesn't exist yet, runscripts/init.shfirst. -
Default path — call
scripts/add-todo.shwith the priority, effort, title, and description. This inserts the canonical line into the right## P*lane and re-validates. Add--backlogif the conversation produced enough investigation that abacklog/<slug>.mddoc is worth scaffolding.scripts/add-todo.sh --priority "P?" --effort M \ --title "Try Rspress for docs" \ --description "Evaluate AI-native docs framework alternative" -
Quick-capture path — append to
backlog/inbox.mdwhen the user isn't sure of priority/effort yet, or is mid-thought:echo "- $UNSTRUCTURED_THOUGHT" >> backlog/inbox.mdLater (this session or next), run
scripts/sweep-inbox.shto formalize the loose lines intoTODO.mdone at a time. The sweeper prompts for missing fields per line; in--batchmode it only processes lines that already havepriority=… effort=… title="…" description="…"pairs and leaves ambiguous ones in place. -
Manual edit path — only when scripts can't help. Use the syntax from
references/tag-schema.mdand runscripts/todo-kanban.sh --validate-onlyafterwards. -
If you wrote a
backlog/<slug>.md(either via--backlogor by hand), make sure the TODO line ends with→ [research](backlog/<slug>.md)so the index points to the doc.
3. Mid-conversation, when you finish debugging something tricky
Signals: "phew, that took a while", "weird, the error didn't say anything about X", "this is the third time we've hit this", or you find yourself reconstructing context that isn't in any doc.
- Create
pitfalls/<symptom-slug>.mdimmediately fromassets/pitfall-doc.md.template, while the trace is fresh. Title the doc by the symptom, not the root cause — you'll search by what you're seeing, not by what you eventually learned. - Copy verbatim error messages — never paraphrase, it kills grep-ability.
- If the trap is severe (silent corruption / cross-machine recurrence /
non-obvious workaround), surface it: "should this graduate to a Hard
invariant in AGENTS.md?" — see
references/when-to-add-docs.md.
4. When implementing a TODO.md item
In the same commit:
- Run
scripts/promote-todo.sh --title "<substring>" --summary "<what shipped>". It removes the active line and inserts the datedDoneentry, then re-validates. It refuses to run if the substring matches zero or more than one active item. - If a
backlog/<slug>.mdexists, set itsStatus: shipped(don't delete — historical record may inform adjacent decisions). - If shipping uncovered a trap, write a
pitfalls/<slug>.mdfor it.
Optional: td integration
If the project uses td for in-flight agent work,
the scripts detect it (PKH_TD=auto|on|off, default auto) and bridge one
way. Git stays the source of truth. A td issue labelled pkh with the same
title points at its TODO.md item, and TODO.md never stores td ids, which
are machine-local.
- Starting an item:
scripts/start-todo.sh --title "<substring>"creates or reuses the td issue and starts it. promote-todo.shthen prints a harvest-then-review hint and never closes the issue.todo-kanban.shmarks in-flight items and lists orphaned issues.init.shappends a routing snippet to the agent contract when td is present.- "Maybe later" still goes to
add-todo.sh, nottd create/td defer.
Without td, nothing changes. Layering, cross-machine caveats, the td exit
plan, and GitHub Issues / Linear guidance are in
references/integrating-trackers.md.
When a TODO entry needs a backlog/ doc, when a debug needs a pitfalls/ doc
Decision rules and the upgrade path to AGENTS.md invariants live in
references/when-to-add-docs.md. Read it
the first time you set up the harness; consult it again whenever you're
unsure which surface a piece of knowledge belongs in.
Tag schema
Two orthogonal axes, validated by scripts/todo-kanban.sh. See
references/tag-schema.md for the full schema,
useful tag combinations, and the exact validator-checked syntax.
Anti-patterns
Common mistakes to avoid (e.g., spawning IDEAS.md alongside TODO.md,
titling pitfalls by root cause, paraphrasing errors). Full list in
references/anti-patterns.md.
Deployment exclusion
TODO.md, backlog/, and pitfalls/ are maintainer-facing repo metadata,
not files to ship. Cheatsheet for chezmoi / npm / pip / Docker in
references/deployment-exclusion.md.
scripts/init.sh --deployment ... prints the exact lines to add.
Templates and bundled assets
assets/TODO.md.template—TODO.mdskeleton with example items per laneassets/backlog-README.md.template—backlog/index + when-to-add rulesassets/backlog-doc.md.template— single backlog doc (context-first)assets/pitfalls-README.md.template—pitfalls/index + cross-reference table for traps documented elsewhereassets/pitfall-doc.md.template— single pitfall doc (symptom-first)assets/agent-guidance.md.template— snippet forAGENTS.md/CLAUDE.mdassets/readme-roadmap.md.template— snippet for projectREADME.mdassets/td-routing.md.template— td ↔TODO.mdrouting snippet (appended byinit.shwhen td is detected)scripts/init.sh— one-shot setupscripts/todo-kanban.sh— validator + Markdown kanban renderer (also supports--jsonand--validate-only)scripts/add-todo.sh— structured insert into## P*lane;--backlogalso scaffoldsbacklog/<slug>.mdscripts/promote-todo.sh— atomic active-→-Done move with re-validationscripts/sweep-inbox.sh— triagebacklog/inbox.md→add-todo.shscripts/start-todo.sh— optional td bridge: start an item as a td issuescripts/_lib/todo-match.sh,scripts/_lib/td-bridge.sh— shared helpers
Reference implementation
A live example of this harness is at
daviddwlee84/dotfiles:
TODO.md,backlog/,pitfalls/directories at repo rootAGENTS.md### Long-term backlog → TODO.md + backlog/and### Past pitfalls → pitfalls/sectionsREADME.md## Roadmap & lessons learnedsection
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/daviddwlee84/agent-skills/project-knowledge-harness">View project-knowledge-harness on skillZs</a>