agent-logger

name	agent-logger
description	Records agent logs with structured markdown files. Invoke when completing complex tasks, learning new knowledge, making serious errors, being corrected by user, when no logs in recent 8 conversations, when self-deemed necessary, or when user requests logging.

Agent Logger

This skill creates structured log entries for the agent to track experiences, learnings, and reflections.

When to Use

Invoke this skill in these scenarios:

• After completing a complex task: When finishing multi-step or non-trivial work
• When learning new knowledge: After discovering new technologies, patterns, or insights
• After making serious errors: When significant mistakes occur that should be documented for future reference
• When being corrected by user: When the user corrects your mistakes or provides corrections to your responses
• When no logs in recent 8 conversations: When the last 8 conversation turns have not resulted in any log entries
• Self-reflection: When you deem it necessary to record important information
• User request: When the user explicitly asks to log something

Logging Process

Step 0: Review What Actually Happened (MANDATORY)

Before brainstorming angles, briefly scan the conversation and ask:

• What did we debate, argue about, or go back and forth on?
• What constraints or limitations surprised us?
• What alternatives were considered and rejected?
• What was the user most concerned about?

These are the "meat" of the task — code can always be read from the repo, but the why behind decisions is ephemeral and must be captured now.

Step 0.5: Brainstorm Logging Angles (MANDATORY)

Before writing any log, pause and brainstorm what angles exist for this task. Complex tasks often warrant multiple logs from different perspectives. Skipping this step leads to missed insights.

Brainstorm Checklist

Go through these questions:

1. Result angle — What was accomplished? What changed? (→ type: log)
2. Decision angle — What design decisions were made and WHY? What constraints forced the choice? What alternatives were rejected and for what reasons? This is often the most valuable angle — the reasoning behind choices fades faster than the code itself. Record all non-obvious trade-offs. (→ type: log, learning, or reflection)
3. Learning angle — What did I learn? What surprised me? What would I do differently? (→ type: learning)
4. Error angle — What went wrong? How was it fixed? What prevented it from happening again? (→ type: error, use error_pattern to classify)
5. Process angle — Was the process efficient? What bottlenecks existed? How could the workflow improve? (→ type: reflection)
6. Collaboration angle — Did interaction with other agents/tools/reviewers yield insights? (→ type: learning)

Decision Rules: Split or Combine?

Situation	Action
Only one angle has substance	Write 1 log, skip the rest
Two angles are closely related and each is thin	Combine into 1 log with clear sections
Each angle has substantial content (3+ paragraphs)	Split into separate logs, cross-link them
A "result" log exists but "learning" angle is rich	Create a separate learning log (e.g., a complex bug fix where the lesson deserves its own space)

Step 1: Get Current Time

• Get current local time in ISO 8601 format with timezone offset
• Format example: 2026-03-18T20:56:00+08:00
• ⚠️ Trap (JavaScript): new Date().toISOString() returns UTC time (ending in Z). Simply doing replace('Z', '+08:00') changes the label but not the actual time value, causing a multi-hour discrepancy!
• Correct approach (system commands, zero dependencies):
  • Windows (PowerShell): Get-Date -Format "yyyy-MM-ddTHH:mm:ssK"
  • Linux/macOS (bash/zsh): date +"%Y-%m-%dT%H:%M:%S%z" | sed 's/\([+-][0-9]\{2\}\)\([0-9]\{2\}\)$/\1:\2/'

Step 2: Create Log Directory

• Check if <workspace>/.log/<yyyy>/<MM>/<dd>/ exists
• If not, create the directory structure (year/month/day nested directories)
• <workspace> is the root directory of project workspace

Step 3: Generate Log File

• Create markdown file in the date directory
• File naming format: log-<topic>.md
• Example: log-completed-task.md

Log File Structure

YAML Frontmatter

---
title: "Topic Title" # Always use English for title
created: "2026-03-18T20:56:00+08:00"
type: "log"  # or "learning", "error", "reflection", "refactor", etc.
author: "<当前AI模型> via <当前Agent平台>"  # AI Model via Agent Platform/Tool
tags: ["#tag1", "#tag2", "#tag3"] # Use graph-compatible tags
language: "zh"  # or "en", etc.
error_pattern: "<错误模式>"  # Optional, for type=error only. Classify the error pattern for cross-log retrieval. Examples: "信息虚构", "流程违规", "修改不完整", "工具盲区"
---

Markdown Content

# Topic Title

**Time**: 2026-03-18T20:56:00+08:00

**Tags**: #tag1 #tag2 #tag3

## Content

[Detailed log content here]

Content Guidelines

Language

• YAML frontmatter title: Always use English for consistency and cross-language linking
• Markdown content: Use the user's preferred language for all content
• Markdown headings: Use the user's preferred language (same as content)
• Match the language used in the conversation

One Topic Per Document

• Single focus: Each log document should focus on only one topic or theme
• Multiple topics: If you need to record multiple topics, create separate log documents for each
• Benefits: This makes logs easier to search, reference, and connect in knowledge graphs
• Examples:
  • ✅ Good: One document for "Learning React Hooks", another for "Learning Redux"
  • ❌ Bad: One document mixing both React Hooks and Redux learnings
• Related topics: Use bidirectional links [[Topic Name]] to connect related documents

Privacy and Security

• Never log sensitive information: Do not include passwords, cookies, tokens, API keys, authentication credentials, or any other sensitive data
• Use placeholders: Replace sensitive information with descriptive placeholders
• Examples of sensitive data to avoid:
  • Passwords: password123 → YOUR_PASSWORD
  • API Keys: sk-1234567890abcdef → YOUR_API_KEY
  • Tokens: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... → YOUR_TOKEN
  • Cookies: session_id=abc123 → YOUR_COOKIE
  • Database credentials: user=admin&pass=secret → DB_CREDENTIALS
• Why this matters: Logs may be shared, backed up, or accessed by others. Protecting sensitive information prevents security breaches
• General principle: If it's a secret, authentication credential, or personally identifiable information, use a placeholder

Path Handling

• Never log fragile file paths outside .log directory: Do not include absolute paths, long relative paths, or ../ traversal paths in log content — these break when files are reorganized. Short conventional module names used as descriptive labels (e.g., models/user.py, hooks/useState.ts) are acceptable as identity references, not location instructions
• Paths are ephemeral: Files get moved, renamed, deleted, or reorganized constantly. Both d:\project\src\utils.js and src/utils.js become equally useless once the file changes location or no longer exists
• Reference code by identity, not location: When referring to code, use descriptive identifiers instead of paths:
  • Use file name + entity name: helpers.js 中的 formatDate() 函数, UserModel class in models/user.py
  • Use inline code snippets: Paste the relevant code directly into the log so it's self-contained
  • Use descriptive labels: 项目根目录的 package.json, agent-logger skill 的 SKILL.md
• Use bidirectional links [[]] for cross-references, never [](): The standard markdown link syntax [](path/to/file) requires a real filesystem path and breaks when the target moves. Use bidirectional wikilinks [[Topic Name]] instead — they are purely semantic identifiers with no path dependency
  • Uniqueness is required: The link target must be uniquely identifiable. Generic names like [[SKILL]] or [[README]] are ambiguous when multiple skills/repos exist
  • ⚠️ CRITICAL: Always use the SHORTEST name that is globally unique. Do NOT default to long namespace-prefixed names. Follow this decision order:
    1. Try filename only first (shortest): [[dream-entry-selector.py]], [[prs]]
    2. If not unique, add parent directory: [[log-memory-searcher/SKILL]], [[gh-cli/references/prs]]
    3. If still not unique, add more levels until unique: [[agent-logger/skills/log-memory-searcher/SKILL]]
    4. Validation rule: Always verify with fd after writing. If fd returns exactly 1 match, the name is good. If 0 or 2+, adjust.
  • Why shortest? Long paths are fragile (break on file moves), harder to read, and signal false precision. A wikilink is a semantic identifier, not a filesystem address.
  • Suffix rules:
    • .md files: No suffix needed — [[agent-logger/SKILL]] links to agent-logger/SKILL.md (standard wikilink convention)
    • Non-md files: Keep the suffix — [[ollama-tool-call-demo.ts]], [[package.json]] to distinguish file types
  • Description required: Every wikilink must be followed by a brief text description explaining the relationship or context. A bare [[link]] without explanation is insufficient — the reader cannot understand why the link is relevant without following it
    • ✅ Good: [[dream-entry-selector.py]]：本次新增的入梦提示选择脚本
    • ✅ Good: [[agent-logger/SKILL]]：日志记录规范，定义了 wikilink 用法
    • ❌ Bad: [[dream-entry-selector.py]] — no description, unclear why it's linked
  • ⚠️ CRITICAL (file-reference links only): Link target must match actual filename: The wikilink target (before | if present) must be the real filename (minus .md suffix), not a "logical name" or "abbreviation" you invent. Always verify the actual filename before constructing the link. If you want a human-friendly display name, use the pipe alias syntax [[actual-filename|Display Name]]. Concept/topic links (plain names without /) are allowed and are not required to match an existing file.
    • ✅ Good: [[log-chrome-cdp-phase1-reverse]] — matches actual filename log-chrome-cdp-phase1-reverse.md
    • ✅ Good: [[log-chrome-cdp-phase1-reverse|Phase 1 逆向能力]] — pipe alias: target matches filename, display is human-friendly
    • ❌ Bad: [[chrome-cdp-phase1-reverse]] — "logical name" that doesn't match the actual filename (missing log- prefix)
    • ❌ Bad: [[phase1]] — abbreviated name that doesn't match any file
  • Pipe alias syntax [[filename|Display Text]]: Use when the actual filename is long or not descriptive enough for inline reading. The part before | is the link target (must match filename), the part after | is the display text.
    • ✅ [[log-chrome-cdp-phase3-experience|Phase 3 体验完善]]：target matches file, display is concise
    • ✅ [[dream-entry-selector.py|入梦提示选择器]]：target matches file, display is localized
    • ❌ [[Phase 3 体验完善]] — no pipe, display text used as target, won't match any file
  • Examples (ordered from preferred to acceptable):
    • ✅ Best (shortest & unique): [[dream-entry-selector.py]]：入梦提示选择脚本, [[prs]]：PR 工作流参考, [[pr-reviews]]：PR 审查参考
    • ✅ Good (needs prefix for uniqueness): [[gh-cli/SKILL]]：GitHub CLI skill, [[agent-logger/SKILL]]：日志记录 skill, [[weread-cli/utils]]：微信读书工具函数
    • ⚠️ Acceptable but verbose (only when shorter name is ambiguous): [[agent-logger/skills/log-memory-searcher/SKILL]]
    • ❌ Bad: [SKILL.md](../../skills/agent-logger/SKILL.md), [helpers.js](src/utils/helpers.js) — uses file paths
    • ❌ Bad: [[SKILL]], [[README]], [[utils]] — not unique, ambiguous targets
    • ❌ Bad: [[log-memory-searcher/scripts/dream-entry-selector.py]] — unnecessarily long when [[dream-entry-selector.py]] is already unique
• .log directory is the only exception: Paths within the .log directory structure (e.g., .log/2026/04/13/completed-task.md) are stable and acceptable, as they are managed by this skill itself
• Why this matters: A log entry saying "fixed a bug in src/utils/helpers.js" is worthless when that path no longer exists. But "fixed a bug in the formatDate() function that caused timezone offset errors" remains useful forever, and the inline code snippet preserves the exact context
• Stable external URLs are acceptable: Links to GitHub PRs, issues, documentation, or other permanent web resources (e.g., https://github.com/owner/repo/pull/34) are fine — they are stable identifiers, not fragile filesystem paths. Unlike local file paths, these URLs are designed to be permanent references.

Knowledge Graph Friendly Syntax

Use markdown syntax that supports knowledge graph generation:

• Tags: Use graph-compatible tags like #concept, #technology
• Links: Create bidirectional links between related entries
• Headings: Use clear hierarchical structure (H1, H2, H3)
• Lists: Use bullet points for key takeaways
• Code blocks: Include relevant code examples
• Tables: Use tables for structured information

Cross-Language Association

• If content is not in English, add bilingual tags for cross-language linking
• Example: For Chinese content about "React", add tags: #React #react #前端
  • #React - English tag (capitalized)
  • #react - English tag (lowercase, for case-insensitive search)
  • #前端 - Chinese tag
• This helps knowledge graphs connect documents across languages
• Bilingual tags ensure documents in different languages can reference the same concepts

Example Log Entries

Example 1: Tech notes (baseline — use when there's no deeper angle)

---
title: "Learned about React Hooks"
created: "2026-03-18T20:56:00+08:00"
type: "learning"
author: "<当前AI模型> via <当前Agent平台>"
tags: ["#React", "#Hooks", "#frontend", "#react", "#hooks"]
language: "zh"
---

# 学习了React Hooks

**Time**: 2026-03-18T20:56:00+08:00

**Tags**: #React #Hooks #frontend

## 我学到了什么

今天我学习了React Hooks，这是一些函数，让你可以在函数组件中使用React的状态和生命周期特性。

### 核心概念

- **useState**: 用于管理组件状态
- **useEffect**: 用于副作用
- **useContext**: 用于消费上下文

### 代码示例

```javascript
const [count, setCount] = useState(0);

useEffect(() => {
  document.title = `Count: ${count}`;
}, [count]);
```

## 相关主题

- [[React Components]]：组件化开发基础
- [[State Management]]：状态管理方案

Example 2: Design decision log (deep — the more valuable kind)

Scenario: Refactored a Chrome automation tool's connection layer from user-manual to auto-launch. Multiple non-trivial design decisions were made.

---
title: "Chrome CDP Auto-Launch Design Decisions"
created: "2026-03-18T20:56:00+08:00"
type: "learning"
author: "<当前AI模型> via <当前Agent平台>"
tags: ["#design-decision", "#automation", "#architecture", "#设计决策", "#自动化", "#架构"]
language: "zh"
---

# Chrome CDP 自动启动——设计决策与讨论

**Time**: 2026-03-18T20:56:00+08:00

**Tags**: #design-decision #automation #architecture

## 1. 问题本质

旧方案要求用户手动开启远程调试 + 每次弹窗确认，对自动化是结构性障碍。
旧方案唯一优势：共享用户默认 profile 的 cookies。

## 2. 核心设计决策

### 决策 1：不能使用 Chrome 默认 profile

Chrome 136+ 不再支持在默认 profile 上启用远程调试——在已运行的 Chrome 上添加 `--remote-debugging-port` 会报错或静默忽略。
→ **要么手动开启（旧方案），要么独立 profile（新方案），没有中间路线。**

### 决策 2：沿用 RUNTIME_DIR 而非硬编码系统路径

`RUNTIME_DIR` 是现有运行时数据目录，把 Chrome profile 放在其下统一管理，清理时删除整个目录即可。
| 方案 | 路径示例 | 优劣 |
|------|---------|------|
| 系统固定路径 | `C:\Temp\chrome-profile` | 简单，但卸载后残留 |
| RUNTIME_DIR 子目录 | `<runtime>/chrome-profile` | 统一管理，与 socket/cache 同目录 |

### 决策 3：Chrome 不随 daemon 退出而关闭

Chrome 不是无头浏览器，用户也可能使用这个窗口。强行退出导致困惑和数据丢失。
→ daemon 空闲 120min 退出，Chrome 持续运行。下次命令复用同一实例。

### 决策 4：CDP_CHROME_PATH 暂不实现

Windows/macOS 已通过系统机制解决路径发现问题，Linux 可依赖 PATH。
当前无使用场景，实现后反而需要维护和文档化。

## 3. 审查中的关键讨论

- 第一轮：Chrome 未安装的错误处理、fetch 超时控制（确认无需）、浏览器退出机制（确认不需要）
- 第二轮：错误消息引用未实现功能的 bug、WSL 遗留代码、CDP_PORT=0 边界
- 第三轮：测试硬编码路径导致不可移植、daemon socket 缺少 error 事件处理

## 4. 新旧方案最终对比

| 维度 | 旧方案 | 新方案 |
|------|--------|--------|
| Chrome 启动 | 用户手动 | 自动 |
| 弹窗确认 | 每次 attach/open | 无 |
| Cookies | 共享默认 profile | 独立持久化 |

## 相关日志

- [[log-chrome-cdp-auto-launch-completed|chrome-cdp-auto-launch-completed]]：功能交付记录，含 GitHub PR 链接

Why this example is better: The React Hooks log captures what (API surface). The design decision log captures why (constraints, rejected alternatives, trade-offs). Six months later, the why is what you won't remember — the what is always available in the code.

Log Types

The following are common type references, but not limited to — you can define new types as needed:

Type	Description	Use When
log	General task completion	Finishing routine tasks
learning	New knowledge acquired	Learning new technologies or concepts
error	Mistakes and lessons	Documenting errors and fixes. Use error_pattern frontmatter field to classify (e.g., "信息虚构", "流程违规", "修改不完整", "工具盲区")
reflection	Self-reflection	Thinking about improvements or insights
refactor	Code or structure refactoring	When improving the internal structure of code or directories

Best Practices

1. One topic per document: Focus each log on a single topic for better organization
2. Protect sensitive information: Never log passwords, tokens, keys, or credentials - use placeholders instead
3. Avoid real file paths: Never log any filesystem paths (absolute or relative) outside .log directory - reference code by identity (function/class name + file name) or inline snippets instead
4. Be specific: Use clear, descriptive titles
5. Include context: Explain why the log entry matters
6. Add tags: Use relevant tags for easy retrieval
7. Link related entries: Create connections between related logs
8. Keep it structured: Use consistent formatting
9. Document learnings: Focus on what was learned or achieved
10. Note improvements: Record ideas for future improvements

Wikilink Validation

After writing a log, manually check file-reference bidirectional links using fd:

What to validate: Only validate links that reference actual files (contain / path separator or known skill namespaces like gh-cli/, agent-logger/). Skip concept/topic links (plain names without /) — these are forward references that may not have files yet.

⚠️ MUST use exact fd -p pattern, NEVER use fuzzy keyword search: Running fd "keyword" without -p will match any file containing that keyword, giving false confidence that a broken link is valid. Always use the -p (full path regex) flag with the anchored pattern shown below.

# Check a wikilink: convert [[path/to/file]] to fd pattern
# For pipe aliases [[filename|Display Text]], only validate the part before |
# IMPORTANT: Use path separator anchor (\\|/) to avoid false positives (e.g., [[dream-mode]] should not match pr-dream-mode.md)
# (\\|/) is cross-platform: matches \ on Windows and / on Linux/macOS
fd -p "(\\|/)path/to/file.md$" <workspace> --hidden --no-ignore --max-results 5

# Examples:
# [[gh-cli/SKILL]]              →  fd -p "(\\|/)gh-cli(\\|/)SKILL.md$" <workspace> --hidden --no-ignore --max-results 5
# [[ollama-tool-call-demo.ts]]  →  fd -p "(\\|/)ollama-tool-call-demo.ts$" <workspace> --hidden --no-ignore --max-results 5
# [[dream-mode]]                →  fd -p "(\\|/)dream-mode.md$" <workspace> --hidden --no-ignore --max-results 5
# [[log-chrome-cdp-phase1-reverse|Phase 1]]  →  fd -p "(\\|/)log-chrome-cdp-phase1-reverse.md$" <workspace> --hidden --no-ignore --max-results 5
# [[Topic Name]]                →  SKIP (concept link, no file required)
#
# ❌ WRONG — fuzzy keyword search, will give false positives:
# fd "phase1" D:\agentSpace\.log   ← matches ANY file with "phase1" in name, can't detect missing prefix

Interpret results:

• 1 match: Link is valid and unique ✅
• 0 matches: BROKEN — target file doesn't exist or path is wrong ❌
• 2+ matches: AMBIGUOUS — use more specific path in the link (e.g., [[gh-cli/SKILL]] instead of [[SKILL]]) ⚠️

Requirements: Install fd (cross-platform):

• Windows: winget install sharkdp.fd
• macOS: brew install fd
• Linux: check package manager for fd-find or download from GitHub releases

Pattern rules:

• Always add path separator anchor (\\|/) before the filename to avoid false positives (e.g., dream-mode.md$ would match pr-dream-mode.md; (\\|/)dream-mode.md$ won't). This is cross-platform: matches \ on Windows and / on Linux/macOS
• Replace / in wikilink path with (\\|/) for cross-platform compatibility
• .md files: append .md$ to the pattern (anchor to filename end, excludes .bak, .old etc.)
• Non-.md files: keep original suffix + $
• Always use --max-results 5 to limit output
• Always use --hidden to include hidden directories (e.g., .log/ which stores agent logs)
• Always use --no-ignore to bypass .gitignore rules (workspace may gitignore directories that contain link targets)
• Regex safety: If link target contains regex metacharacters (., (, ), [, ], +, ?), escape them with \ in the fd pattern. In practice, wikilink targets rarely contain these characters

Implementation Notes

• All logs are stored in <workspace>/.log/ directory
• Each day gets its own nested directory: <year>/<month>/<day>/
• Files are named with log- prefix for easy identification
• Use absolute paths when creating directories and files
• Ensure proper error handling for file operations