@xiaotianxt/skills 0.1.0

package/skills/learn/assets/errorlog.template.typ

@@ -0,0 +1,61 @@
+#set page(paper: "a4", margin: 1.8cm)
+#set text(font: ("PingFang SC", "Arial Unicode MS"), size: 10.5pt, lang: "zh")
+#set par(justify: true, leading: 0.62em)
+
+= {TOPIC} 错题与误区日志
+
+用途：记录学习过程中暴露出的错误、模糊理解、概念混淆、迁移失败和关键盲点。这个文件决定后续复习顺序。
+
+记录规则：
+
+- 只记录会影响后续理解或应用的错误，不记录每个小瑕疵。
+- 保留学习者原始回答的意思，避免事后美化。
+- 每条错误必须包含正确理解和下一次复习动作。
+- 连续两次跨会话答对，才可以从 `review` 改为 `closed`。
+
+== 错误分类
+
+#table(
+  columns: (3.0cm, 1fr),
+  inset: 5pt,
+  align: left,
+  [类型], [说明],
+  [concept], [概念混淆。],
+  [source], [没有说清楚依据来自哪份资料，或脱离资料泛泛而谈。],
+  [application], [不能迁移到新场景。],
+  [boundary], [忽略边界条件或失败模式。],
+  [terminology], [术语不熟。],
+  [method], [解题方法、分析步骤或学习策略错误。],
+  [process], [学习流程问题，例如跳过提问或复盘。],
+)
+
+== 活跃错误表
+
+#table(
+  columns: (1.1cm, 1.6cm, 1.7cm, 2.3cm, 1fr, 1fr, 2.0cm, 1.5cm),
+  inset: 3.6pt,
+  align: left,
+  [ID], [日期], [课程], [类型], [错误表现], [修正解释], [复习日期], [状态],
+  [E000], [{DATE}], [Plan], [process], [尚未开始正式问答。], [从 L001 开始，用验证问题暴露真实薄弱点。], [{DATE}], [open],
+)
+
+== 新错误记录模板
+
+#table(
+  columns: (3.0cm, 1fr),
+  inset: 5pt,
+  align: left,
+  [字段], [内容],
+  [ID], [E001],
+  [日期], [YYYY-MM-DD],
+  [课程], [L???],
+  [类型], [concept / source / application / boundary / terminology / method / process],
+  [原问题], [助教提出的验证问题。],
+  [学习者回答], [保留学习者原意，避免事后美化。],
+  [错误表现], [具体指出错在哪里。],
+  [正确理解], [用简单语言修正。],
+  [为什么重要], [如果这个错误保留下来，会影响哪类理解、题目、项目或判断。],
+  [复习动作], [下一次如何验证是否真正掌握。],
+  [复习日期], [YYYY-MM-DD],
+  [状态], [open / review / closed],
+)

package/skills/learn/assets/reading-sequence.template.md

@@ -0,0 +1,23 @@
+# {TOPIC} Reading Sequence
+
+Goal: {GOAL}
+
+## First Pass
+
+### L001: Establish the Goal and Map the Sources
+
+Read:
+
+- `materials/source-index.md`
+
+Questions:
+
+- What should the learner be able to do after this topic?
+- Which sources are authoritative?
+- What is the first small unit worth teaching?
+
+Output:
+
+- Update `tasklog.typ`.
+- Ask verification questions before marking L001 done.
+

package/skills/learn/assets/source-index.template.md

@@ -0,0 +1,17 @@
+# {TOPIC} Source Index
+
+Goal: {GOAL}
+
+## Source Table
+
+| Priority | Source | Local Path / URL | Type | Use |
+|---|---|---|---|---|
+| must | TBD | TBD | book/course/doc/paper/video | Core source |
+
+## Collection Rules
+
+- Prefer primary sources.
+- Convert enough material into AI-readable text to teach accurately.
+- Keep raw files and links; write original notes instead of copying long copyrighted text.
+- Add sources as questions demand them; do not block learning on exhaustive collection.
+

package/skills/learn/assets/tasklog.template.typ

@@ -0,0 +1,57 @@
+#set page(paper: "a4", margin: 1.8cm)
+#set text(font: ("PingFang SC", "Arial Unicode MS"), size: 10.5pt, lang: "zh")
+#set par(justify: true, leading: 0.62em)
+
+= {TOPIC} 学习任务日志
+
+目标：{GOAL}
+
+使用规则：
+
+- 每次讲解后，助教必须提出验证问题。
+- 学习者回答后，助教必须评分并更新本日志。
+- 答错、含糊、只会背但不能应用的内容，必须同步写入 `errorlog.typ`。
+- 状态使用 `todo`、`doing`、`review`、`done`。
+- `done` 的条件是：能用自己的话解释，能应用到新场景，能指出常见误判。
+
+== 评分规则
+
+#table(
+  columns: (1.2cm, 3.2cm, 1fr),
+  inset: 5pt,
+  align: left,
+  [分数], [判定], [标准],
+  [0], [未掌握], [无法解释核心概念，或给出误导性答案。],
+  [1], [初步听懂], [能复述定义，但不能独立举例或应用。],
+  [2], [基本掌握], [能解释含义，并能应用到一个合理场景。],
+  [3], [可实战沟通], [能说明边界、误区、失败模式和下一步行动。],
+)
+
+== 学习计划
+
+#table(
+  columns: (1.4cm, 4.2cm, 1.5cm, 1.4cm, 1fr),
+  inset: 4pt,
+  align: left,
+  [课], [主题], [优先级], [状态], [目标],
+  [L001], [建立问题和目标], [must], [doing], [明确学习目标、资料范围、输出标准和第一轮问题。],
+)
+
+== 讲解会话日志
+
+#table(
+  columns: (2.2cm, 1.8cm, 1.8cm, 1.8cm, 1.7cm, 1fr),
+  inset: 4pt,
+  align: left,
+  [日期], [课程], [状态], [平均分], [错题数], [下一步],
+  [{DATE}], [Plan], [doing], [-], [0], [开始收集资料并建立第一轮学习顺序。],
+)
+
+== 验证问题模板
+
+1. 概念解释：请用自己的话解释本节最重要的概念。
+2. 来源依据：资料中哪一处支持这个说法？
+3. 应用场景：把概念应用到一个新例子。
+4. 误判识别：最容易犯的错误解释是什么？
+5. 下一步：如果证据不足，下一步应该读什么、问什么或做什么？
+

package/skills/learn/assets/workbook.template.typ

@@ -0,0 +1,60 @@
+#set page(paper: "a4", margin: 1.8cm)
+#set text(font: ("PingFang SC", "Arial Unicode MS"), size: 10.5pt, lang: "zh")
+#set par(justify: true, leading: 0.62em)
+
+= {TOPIC} 学习工作本
+
+目标：{GOAL}
+
+这个文件用于记录每节课的讲解结构、关键例子、验证问题和修正后的理解。错题本只记录错误；工作本记录学习过程。
+
+== 使用方法
+
+每个小节按这个结构记录：
+
+#enum[
+  Source：本节基于哪些资料。
+][
+  Map：本节知识地图。
+][
+  Explanation：完整讲解。
+][
+  Example：例题、业务场景、代码场景或案例。
+][
+  Questions：验证问题。
+][
+  Correction：回答后的修正说明。
+][
+  Drill：下一次复习或迁移练习。
+]
+
+== L001：起步
+
+=== Source
+
+待补。
+
+=== Map
+
+待补。
+
+=== Explanation
+
+待补。
+
+=== Example
+
+待补。
+
+=== Questions
+
+待补。
+
+=== Correction
+
+待补。
+
+=== Drill
+
+待补。
+

package/skills/learn/references/learning-science.md

@@ -0,0 +1,103 @@
+# Learning Science Reference
+
+Use these principles to design or adjust learning workflows.
+
+## Evidence-Backed Defaults
+
+### Retrieval Practice
+
+Testing is not only assessment; it is a learning event. Prefer short-answer questions, explanation prompts, trace interpretation, and transfer questions over recognition-only checks.
+
+Implementation:
+
+- Teach a small unit.
+- Ask the learner to explain or apply it without looking.
+- Give corrective feedback.
+- Log the exact misconception if the answer is weak.
+
+Source anchors:
+
+- Dunlosky et al. (2013): practice testing is high utility.
+- Roediger & Karpicke (2006): retrieval after studying prose improved later retention.
+
+### Distributed Practice and Successive Relearning
+
+Spacing matters. Review should happen after a gap, and practice should continue until the learner can retrieve to criterion.
+
+Implementation:
+
+- Keep error items `open`, `review`, or `closed`.
+- Review open items after time has passed or when the user asks.
+- Close only after repeated correct retrieval in separate sessions.
+- Do not force a rigid schedule that annoys the user.
+
+Source anchors:
+
+- Cepeda et al. (2006): spacing effects are broadly supported, with optimal gaps depending on retention interval.
+- Rawson & Dunlosky (2022): successive relearning combines spaced sessions and retrieval to criterion, but cost-benefit matters.
+
+### Formative Feedback
+
+Feedback should answer: where is the learner going, how are they doing, and what should happen next. Feedback should explain the correction, not only mark right/wrong.
+
+Implementation:
+
+- Score answers with a transparent rubric.
+- Write the corrected model.
+- Add a next review action.
+- Avoid generic praise or vague criticism.
+
+Source anchors:
+
+- Shute (2007): formative feedback varies by type and timing; effective feedback includes explanation, hints, or worked examples depending on task and learner.
+
+### Cognitive Load
+
+Learning complex technical material fails when working memory is overloaded by disorganized sources, unnecessary notation, scattered files, or too many simultaneous objectives.
+
+Implementation:
+
+- Convert sources into readable text.
+- Create a reading sequence.
+- Teach in small units.
+- Use worked examples before independent problems for novices.
+- Fade support as competence rises.
+
+Source anchors:
+
+- Sweller, van Merrienboer, & Paas (1998): instructional design should account for working-memory limits, intrinsic load, extraneous load, and schema construction.
+- Kalyuga (2007): learner prior knowledge changes which instructional support helps; too much guidance can hurt advanced learners.
+
+### Active Learning and ICAP
+
+Do not confuse "interactive chat" with active learning. The learner must generate, explain, compare, debug, or transfer.
+
+Implementation:
+
+- Require the learner to explain in their own words.
+- Ask transfer questions: "what tool next?", "what field/module does this become?", "what failure mode follows?"
+- Prefer constructive and interactive activities over passive reading.
+
+Source anchors:
+
+- Freeman et al. (2014): active learning improved STEM outcomes in a large meta-analysis.
+- Chi & Wylie (2014): ICAP orders engagement from passive to active to constructive to interactive.
+
+## Critique of the Folder + Sources + Logs Pipeline
+
+The pipeline is strong because it creates source grounding, retrieval, feedback, and cumulative error memory. It should be adjusted in four ways:
+
+1. Do not over-collect. Start with a minimum viable corpus, then collect more when a question demands it.
+2. Do not over-convert. Convert enough for AI use; keep raw originals and indexes rather than rewriting entire books.
+3. Do not over-log. Log misconceptions that would cause future failure, not every stylistic weakness.
+4. Do not over-schedule review. Use spaced review as a tool, but let the user trigger heavy review unless a deadline requires a plan.
+
+## Practical Design Rule
+
+A good learning workspace has exactly four persistent memories:
+
+1. Source memory: what materials exist and where.
+2. Goal memory: what the learner is trying to become able to do.
+3. Progress memory: what has been covered and scored.
+4. Error memory: what the learner got wrong and how to revisit it.
+

package/skills/learn/scripts/init_learning_workspace.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Initialize a source-grounded learning workspace."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import date
+from pathlib import Path
+
+
+def slugify(value: str) -> str:
+    out = []
+    last_dash = False
+    for ch in value.lower():
+        if ch.isalnum():
+            out.append(ch)
+            last_dash = False
+        elif not last_dash:
+            out.append("-")
+            last_dash = True
+    return "".join(out).strip("-") or "learning-topic"
+
+
+def render(template: str, topic: str, goal: str) -> str:
+    return (
+        template.replace("{TOPIC}", topic)
+        .replace("{GOAL}", goal)
+        .replace("{DATE}", date.today().isoformat())
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("topic", help="Human-readable topic name")
+    parser.add_argument("--path", default=".", help="Parent directory for workspace")
+    parser.add_argument("--name", help="Workspace folder name; defaults to topic slug")
+    parser.add_argument("--goal", default="Build practical, source-grounded mastery.")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing template files")
+    args = parser.parse_args()
+
+    skill_dir = Path(__file__).resolve().parents[1]
+    assets = skill_dir / "assets"
+    root = Path(args.path).expanduser().resolve() / (args.name or slugify(args.topic))
+    root.mkdir(parents=True, exist_ok=True)
+
+    for subdir in ["materials", "notes", "cases", "outputs"]:
+        (root / subdir).mkdir(exist_ok=True)
+
+    files = {
+        "AGENTS.md": assets / "AGENTS.template.md",
+        "tasklog.typ": assets / "tasklog.template.typ",
+        "errorlog.typ": assets / "errorlog.template.typ",
+        "workbook.typ": assets / "workbook.template.typ",
+        "materials/source-index.md": assets / "source-index.template.md",
+        "notes/reading-sequence.md": assets / "reading-sequence.template.md",
+    }
+
+    for rel, template_path in files.items():
+        target = root / rel
+        if target.exists() and not args.force:
+            continue
+        text = render(template_path.read_text(), args.topic, args.goal)
+        target.write_text(text)
+
+    print(root)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/macos-messages/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: macos-messages
+description: Read and search local macOS Messages.app iMessage/SMS history directly through the chat.db SQLite database. Use when the user wants to read, search, or analyze local iPhone messages, SMS, iMessage conversations, or message attachments on this Mac.
+---
+
+# macOS Messages
+
+Direct read-only SQLite access to `~/Library/Messages/chat.db` for local iMessage and SMS history. No CLI wrapper — use `sqlite3` with the queries below.
+
+## Privacy
+
+Chat data is private. Keep all work local. Print only the message content the user asked for. Never export `chat.db` to external services. Treat message bodies, sender identities, and attachment paths as sensitive.
+
+## Setup
+
+The terminal needs **Full Disk Access** in System Settings → Privacy & Security → Full Disk Access. Without it, `~/Library/Messages/chat.db` is permission-denied.
+
+Verify:
+
+```bash
+sqlite3 ~/Library/Messages/chat.db "SELECT COUNT(*) FROM message"
+```
+
+## Schema
+
+Four core tables, three join tables:
+
+| Table | Role |
+| --- | --- |
+| `chat` | Conversation. `chat_identifier` is phone/email/group-id. `display_name` is the group name. |
+| `message` | Individual message. `text` or `attributedBody` holds the body, `date` is timestamp, `is_from_me`=1 means sent. |
+| `handle` | Contact. `id` is phone or email, `service` is iMessage/SMS/RCS. |
+| `attachment` | Media file. `filename` is the on-disk path, `mime_type` is MIME type. |
+
+Join tables: `chat_message_join`, `chat_handle_join`, `message_attachment_join`.
+
+## Text vs attributedBody
+
+**This is the most common pitfall.** `message.text` is frequently NULL because Messages.app stores the body in `attributedBody` (NSKeyedArchiver binary blob) instead. This happens for most SMS, RCS, and rich iMessages. Plain-text iMessages are the main case where `text` is populated.
+
+To extract readable text from `attributedBody`:
+
+```bash
+sqlite3 ~/Library/Messages/chat.db \
+  "SELECT HEX(attributedBody) FROM message WHERE ROWID=<MSG_ID>" \
+  | xxd -r -p | strings | grep -vE '^(NS|__)' | grep -v streamtyped | head -20
+```
+
+To run this in a single pipeline for a full chat read, see **Reading with extraction** below.
+
+## Date Conversion
+
+All timestamps use Mac absolute time (since 2001-01-01). Convert:
+
+```sql
+-- message.date: nanoseconds since 2001-01-01
+datetime(date/1000000000 + 978307200, 'unixepoch', 'localtime')
+
+-- attachment.created_date: seconds since 2001-01-01
+datetime(created_date + 978307200, 'unixepoch', 'localtime')
+```
+
+`978307200` = delta in seconds between Unix epoch (1970-01-01) and Mac epoch (2001-01-01).
+
+## Common Queries
+
+### List recent chats
+
+```sql
+SELECT c.ROWID, c.chat_identifier, c.display_name, c.service_name,
+       datetime(MAX(m.date)/1000000000 + 978307200, 'unixepoch', 'localtime') AS last_msg
+FROM chat c
+JOIN chat_message_join cmj ON c.ROWID = cmj.chat_id
+JOIN message m ON cmj.message_id = m.ROWID
+GROUP BY c.ROWID
+ORDER BY MAX(m.date) DESC
+LIMIT 20
+```
+
+### Find a chat
+
+```sql
+SELECT ROWID, chat_identifier, display_name, service_name
+FROM chat
+WHERE chat_identifier LIKE '%KEYWORD%'
+   OR display_name LIKE '%KEYWORD%'
+LIMIT 10
+```
+
+### Read messages from a chat (with extraction)
+
+Replace `<CHAT_ID>` with the chat ROWID. This extracts text from both `text` and `attributedBody`:
+
+```bash
+sqlite3 ~/Library/Messages/chat.db -separator $'\t' \
+  "SELECT m.ROWID, datetime(m.date/1000000000 + 978307200, 'unixepoch', 'localtime') AS time,
+          CASE WHEN m.is_from_me THEN 'Me' ELSE COALESCE(h.id, m.service) END AS sender,
+          COALESCE(m.text, HEX(m.attributedBody)) AS body
+   FROM message m
+   JOIN chat_message_join cmj ON m.ROWID = cmj.message_id
+   LEFT JOIN handle h ON m.handle_id = h.ROWID
+   WHERE cmj.chat_id = <CHAT_ID>
+   ORDER BY m.date DESC
+   LIMIT 50" \
+  | while IFS=$'\t' read rowid time sender body; do
+      text="$body"
+      if [[ "$body" =~ ^[0-9A-Fa-f]+$ ]] && [ ${#body} -gt 40 ]; then
+        text=$(echo "$body" | xxd -r -p | strings | grep -vE '^(NS|__)' | grep -v streamtyped | tr '\n' ' ' 2>/dev/null | head -c 500)
+      fi
+      echo "$time | $sender | ${text:0:300}"
+    done
+```
+
+For ascending order (oldest first): change `DESC` to `ASC`.
+
+For a quick peek (no extraction, just see which messages have body):
+
+```sql
+SELECT datetime(m.date/1000000000 + 978307200, 'unixepoch', 'localtime') AS time,
+       CASE WHEN m.is_from_me THEN 'Me' ELSE COALESCE(h.id, m.service) END AS sender,
+       CASE WHEN m.text IS NOT NULL THEN SUBSTR(m.text, 1, 80)
+            WHEN m.attributedBody IS NOT NULL THEN '[attributedBody: ' || LENGTH(m.attributedBody) || ' bytes]'
+            ELSE '[empty]' END AS preview
+FROM message m
+JOIN chat_message_join cmj ON m.ROWID = cmj.message_id
+LEFT JOIN handle h ON m.handle_id = h.ROWID
+WHERE cmj.chat_id = <CHAT_ID>
+ORDER BY m.date DESC
+LIMIT 50
+```
+
+### Read messages in a date range
+
+```sql
+WHERE cmj.chat_id = <CHAT_ID>
+  AND m.date >= strftime('%s', '2026-04-01', 'localtime') * 1000000000 - 978307200000000000
+  AND m.date <  strftime('%s', '2026-05-01', 'localtime') * 1000000000 - 978307200000000000
+```
+
+### Search all messages
+
+Searches both `text` and `attributedBody`. Pipe through grep to handle binary extraction:
+
+```bash
+sqlite3 ~/Library/Messages/chat.db -separator $'\t' \
+  "SELECT m.ROWID, datetime(m.date/1000000000 + 978307200, 'unixepoch', 'localtime') AS time,
+          CASE WHEN m.is_from_me THEN 'Me' ELSE COALESCE(h.id, m.service) END AS sender,
+          COALESCE(m.text, HEX(m.attributedBody)) AS body,
+          c.chat_identifier
+   FROM message m
+   JOIN chat_message_join cmj ON m.ROWID = cmj.message_id
+   JOIN chat c ON cmj.chat_id = c.ROWID
+   LEFT JOIN handle h ON m.handle_id = h.ROWID
+   WHERE m.text LIKE '%KEYWORD%' ESCAPE '\'
+      OR HEX(m.attributedBody) LIKE '%' || REPLACE(HEX('KEYWORD'), '00', '') || '%'
+   ORDER BY m.date DESC
+   LIMIT 30" \
+  | while IFS=$'\t' read rowid time sender body chat; do
+      text="$body"
+      if [[ "$body" =~ ^[0-9A-Fa-f]+$ ]] && [ ${#body} -gt 40 ]; then
+        text=$(echo "$body" | xxd -r -p | strings | grep -vE '^(NS|__)' | grep -v streamtyped | tr '\n' ' ' 2>/dev/null | head -c 500)
+      fi
+      echo "$time | $sender | ${text:0:300} | [$chat]"
+    done
+```
+
+The `REPLACE(HEX('KEYWORD'), '00', '')` accounts for UTF-16 encoding in the blob — hex matching handles ASCII text without needing full blob decode.
+
+For a faster SQL-only search (returns matched rows, requires separate extraction):
+
+```sql
+SELECT m.ROWID, datetime(m.date/1000000000 + 978307200, 'unixepoch', 'localtime') AS time,
+       CASE WHEN m.is_from_me THEN 'Me' ELSE COALESCE(h.id, m.service) END AS sender,
+       SUBSTR(COALESCE(m.text, ''), 1, 80) AS snippet,
+       c.chat_identifier
+FROM message m
+JOIN chat_message_join cmj ON m.ROWID = cmj.message_id
+JOIN chat c ON cmj.chat_id = c.ROWID
+LEFT JOIN handle h ON m.handle_id = h.ROWID
+WHERE m.text LIKE '%KEYWORD%' ESCAPE '\'
+   OR HEX(m.attributedBody) LIKE '%' || REPLACE(HEX('KEYWORD'), '00', '') || '%'
+ORDER BY m.date DESC
+LIMIT 30
+```
+
+### Search by contact
+
+Find the handle first:
+
+```sql
+SELECT ROWID, id, service FROM handle WHERE id LIKE '%PHONE_OR_EMAIL%' LIMIT 10
+```
+
+Then get their messages with extraction (replace `<HANDLE_ID>`):
+
+```bash
+sqlite3 ~/Library/Messages/chat.db -separator $'\t' \
+  "SELECT m.ROWID, datetime(m.date/1000000000 + 978307200, 'unixepoch', 'localtime') AS time,
+          COALESCE(m.text, HEX(m.attributedBody)) AS body, m.is_from_me
+   FROM message m
+   WHERE m.handle_id = <HANDLE_ID>
+   ORDER BY m.date DESC
+   LIMIT 50" \
+  | while IFS=$'\t' read rowid time body is_from_me; do
+      text="$body"
+      if [[ "$body" =~ ^[0-9A-Fa-f]+$ ]] && [ ${#body} -gt 40 ]; then
+        text=$(echo "$body" | xxd -r -p | strings | grep -vE '^(NS|__)' | grep -v streamtyped | tr '\n' ' ' 2>/dev/null | head -c 500)
+      fi
+      echo "$time | $([ "$is_from_me" = 1 ] && echo 'Me' || echo '→') | ${text:0:300}"
+    done
+```
+
+### Message counts per chat
+
+```sql
+SELECT c.chat_identifier, c.display_name, COUNT(m.ROWID) AS msg_count
+FROM chat c
+JOIN chat_message_join cmj ON c.ROWID = cmj.chat_id
+JOIN message m ON cmj.message_id = m.ROWID
+GROUP BY c.ROWID
+ORDER BY msg_count DESC
+LIMIT 20
+```
+
+### Get attachments for a message
+
+```sql
+SELECT a.filename, a.mime_type, a.total_bytes
+FROM attachment a
+JOIN message_attachment_join maj ON a.ROWID = maj.attachment_id
+WHERE maj.message_id = <MESSAGE_ID>
+```
+
+### Attachments by date
+
+```sql
+SELECT datetime(a.created_date + 978307200, 'unixepoch', 'localtime') AS time,
+       a.filename, a.mime_type, a.total_bytes
+FROM attachment a
+ORDER BY a.created_date DESC
+LIMIT 30
+```
+
+## Safety
+
+- **Read-only only.** Never run INSERT, UPDATE, DELETE, or DROP against `chat.db`.
+- Always add `LIMIT`. This database can have tens of thousands of rows.
+- When `text` is NULL, extract from `attributedBody` using the pipeline above — never assume a NULL `text` means an empty message.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `unable to open database file` | Grant Full Disk Access to Terminal in System Settings |
+| `database is locked` | Normal when Messages.app is running; sqlite3 handles concurrent reads fine |
+| No results for a known contact | Try both phone number and email in `handle.id`. iMessage uses email, SMS uses phone. |
+| `text` IS NULL | Body is in `attributedBody`. Extract with: `HEX(attributedBody) \| xxd -r -p \| strings \| grep -vE '^(NS\|__)' \| grep -v streamtyped` |
+| Search misses expected messages | Query only searched `text`. Add `OR HEX(m.attributedBody) LIKE '%' \|\| REPLACE(HEX('KEYWORD'), '00', '') \|\| '%'` to cover attributedBody. |

package/skills/memory/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: memory
+description: Query and read past coding-agent session/conversation history, across both opencode and codex. Use when the user wants to recall something discussed in a previous session, search past conversations by keyword, review context from old sessions, or continue prior work. Triggers include "查一下之前的聊天记录", "还记得上次那个...", "look up a past session", "what did we talk about...", or any request to recall historical context.
+---
+
+# Memory
+
+This skill provides read-only access to past conversation history, supporting multiple coding agents.
+
+## Agent detection
+
+Determine which agent you are running under, then load the corresponding reference file:
+
+| Agent | How to detect | Reference file |
+|---|---|---|
+| **OpenCode** | System prompt mentions "opencode" OR you have the `opencode` CLI; DB exists at `~/.local/share/opencode/opencode.db` | [opencode.md](opencode.md) |
+| **Codex (OpenAI)** | System prompt mentions "Codex" or "GPT-5"; sessions in `~/.codex/sessions/` | [codex.md](codex.md) |
+
+**Detection priority:**
+1. Check your system prompt / identity (e.g. "You are Codex" vs "You are opencode").
+2. If ambiguous, check which session store exists on disk.
+
+Once detected, read the corresponding file:
+
+- For **OpenCode**: open `opencode.md` in the same directory as this file.
+- For **Codex**: open `codex.md` in the same directory as this file.
+
+## Common safety rules (both agents)
+
+- **Read-only**: Never modify session data (INSERT, UPDATE, DELETE, file write, etc.).
+- **Limit output**: Always use `LIMIT` or piping (`head`) to avoid flooding context.
+- **Privacy**: Avoid printing API keys, tokens, account emails, or raw error bodies.
+- **WAL/Concurrency**: Both systems support concurrent reads; no need to stop the agent.