# Weekly Report

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-niracler-skill-weekly-report`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [niracler](https://agentstack.voostack.com/s/niracler)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [niracler](https://github.com/niracler)
- **Source:** https://github.com/niracler/skill/tree/main/skills/workflow/weekly-report

## Install

```sh
agentstack add skill-niracler-skill-weekly-report
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Weekly Report

软件研发周报生成助手。自动扫描 `~/code/` 下所有项目的 schedule YAML 和 git log，
结合前几周周报做对比，生成结构化的三段式周报，写入 Obsidian 日记。

## Prerequisites

| Tool | Type | Required | Install |
|------|------|----------|---------|
| git | cli | Yes | `brew install git` |
| reminders-cli | cli | Yes | `brew install keith/formulae/reminders-cli` |
| macOS Calendar | system | Yes | Built-in, access via `osascript` |
| gh | cli | No | `brew install gh` then `gh auth login` — for GitHub PR/Issue data |
| yunxiao | skill | No | For 云效 MR/Task/Bug data (invoke via Skill tool) |

### Path Dependencies

| Path | Purpose | Required |
|------|---------|----------|
| `~/code/*/` | Monorepo workspaces (git repos + schedule YAMLs) | Yes |
| `~/code/*/planning/schedules/*.yaml` | Project schedule definitions | No (skip projects without schedule) |
| `~/code/*/repos/*/` | Sub-repos within each monorepo workspace | No (scanned automatically if present) |
| Obsidian daily notes directory | Daily diary files with Work Log entries + report output | Yes |

The Obsidian vault path is auto-detected by scanning `~/Library/Mobile Documents/iCloud~md~obsidian/`.
If not found, ask the user.

> Do NOT proactively verify tools or paths on skill load. If a command fails due to a
> missing tool, skip that data source and continue with what's available.

## Workflow Overview

1. **Confirm** → 2. **Find previous** → 3. **Collect data** (parallel) → 4. **Draft** → 5. **Review + write** → 6. **Schedule next week**

```text
┌──────────────────────────────────────────────────────────────────┐
│                weekly-report 完整流程（~20min）                    │
└──────────────────────────────────────────────────────────────────┘

  ┌──────────────┐
  │ 用户触发周报  │
  └──────┬───────┘
         │
         ▼
  ┌────────────────────────────────────┐
  │ 1. 确认周期 + 定位文件    (~1min)   │
  └──────┬─────────────────────────────┘
         │
         ▼
  ┌────────────────────────────────────┐
  │ 2. 查找前几周周报         (~1min)   │
  │    提取上周「下周工作计划」         │
  └──────┬─────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────┐
  │ 3. 并行数据收集（subagent）          (~3-5min)   │
  │    ┌─ 本周日记 Work Log（各工作日）              │
  │    ├─ Schedule YAML（本周 + 下周模块）           │
  │    ├─ Git log（~/code/*/ 全扫描）                │
  │    ├─ GitHub PR/Issue（gh CLI）                  │
  │    └─ 云效 MR/Task/Bug（yunxiao skill）          │
  └──────┬──────────────────────────────────────────┘
         │
         ▼
  ┌────────────────────────────────────┐
  │ 4. 交叉比对 + 生成草稿    (~3min)   │
  │    上周计划 vs 本周实际             │
  └──────┬─────────────────────────────┘
         │
         ▼
  ┌────────────────────────────────────┐
  │ 5. 用户审阅 + 修改        (~5min)   │
  │    展示草稿 → 用户调整 → 写入日记  │
  └──────┬─────────────────────────────┘
         │
         ▼
  ┌────────────────────────────────────┐
  │ 6. 创建下周日程 + 提醒    (~3min)   │
  │    Calendar time block             │
  │    Reminders 任务列表              │
  └──────┬─────────────────────────────┘
         │
         ▼
      ┌──────┐
      │ 完成  │
      └──────┘
```

## Step 1: Confirm Period and Target File

- **Report period**: Current week's Monday through Friday
- **Target file**: The day's daily note (usually last workday of the week)
- **Write location**: Under `## 2 Work Log`, as `### 软件研发周报（M/D - M/D）`
- **Diary path**: Scan for Obsidian vault in `~/Library/Mobile Documents/iCloud~md~obsidian/`
  or ask the user if not found

If today is Saturday/Sunday, default to the previous Friday's daily note.
Confirm with the user before proceeding.

## Step 2: Find Previous Reports

Scan recent daily notes (previous 14 days) for the heading pattern `### 软件研发周报`.

From the most recent previous report, extract:

1. **「下周工作计划」section** → baseline for accountability check (what was planned vs what happened)
2. **Format and style** → maintain consistency (project groupings, level of detail, bold patterns)

If no previous report found, skip comparison and proceed — this is normal for the first report.

## Step 3: Parallel Data Collection

Launch subagents concurrently. The five data sources are independent — run as many in
parallel as possible. If any source fails or is unavailable, skip it and continue.

### 3a. Daily Notes (Work Log)

Read the daily notes for each workday in the report period (Monday through Friday).
Extract content under `## 2 Work Log` from each day's note.

This is the richest data source — daily work logs often contain context, decisions, and
details that git commits and PR titles don't capture. Prioritize this content when
writing the report.

### 3b. Schedule YAML Scan

Scan `~/code/*/planning/schedules/*.yaml` — same directory structure as code-sync
(`~/code/*/` monorepo workspaces).

For each YAML found:

1. Read `project`, `title`, `timeline.start`, `phases`, `modules`
2. Calculate the current week number: `ceil((today - timeline.start) / 7)`
3. Extract modules where `weeks` includes current week → this week's work
4. Extract modules where `weeks` includes next week → next week's plan
5. Count `status: done` modules in current phase → progress fraction (e.g., 4/6)

### 3c. Git Log Collection

Scan `~/code/*/` and `~/code/*/repos/*/` for git repos (same candidates as code-sync's
scan.sh pattern), then for each:

```bash
git log --oneline --since="{monday}" --until="{saturday}" --author="{user}" --all
```

Where `{user}` is from `git config user.name`.

Group commits by workspace → repo. This supplements the daily notes — useful for catching
work the user forgot to log in their diary.

### 3d. GitHub Activity (if `gh` available)

```bash
# PRs authored this week
gh search prs --author=@me --created="{monday}..{saturday}" --json repository,title,number,state,url

# Issues authored/assigned this week
gh search issues --author=@me --created="{monday}..{saturday}" --json repository,title,number,state,url
```

Include merged PRs, open PRs, and closed issues in the report. PR numbers and titles
provide concrete references for the boss.

### 3e. 云效 Activity (if yunxiao skill available)

Spawn a subagent to invoke yunxiao skill via Skill tool:

```text
Agent tool:
- subagent_type: general-purpose
- prompt: |
    Invoke the yunxiao skill to query work activity from {monday} to {friday}.
    Get: MRs authored (merged + open), Tasks assigned (modified this week),
    Bugs assigned (modified this week).
    Return: list of items with identifier, title, status, and dates.
```

MR numbers (e.g., MR#67) and task identifiers (e.g., YWQO-4) add traceability to the report.

### Data Source Priority

When the same work appears in multiple sources, merge intelligently:

| Priority | Source | Strength |
|---|---|---|
| 1 | Daily notes | Most context, user's own words, decisions and reasoning |
| 2 | Schedule YAML | Structured progress, phase tracking, module status |
| 3 | GitHub / 云效 | Concrete references (PR#, MR#, issue#, task ID) |
| 4 | Git log | Catch unreported work, verify claims |

The daily notes provide the narrative; schedule YAML provides structure; GitHub/云效
provide traceability; git log fills gaps.

### Data Source Degradation

| Source unavailable | Behavior |
|---|---|
| Daily notes missing for some days | Use available days, note gaps |
| No schedule YAML for a project | Include project based on git/daily notes alone, omit progress fraction |
| `gh` not installed or auth failed | Skip GitHub data, note "GitHub 数据未获取" |
| yunxiao skill unavailable | Skip 云效 data, note "云效数据未获取" |
| Git log returns nothing | Project may have had non-code work (meetings, design) — check daily notes |
| All remote sources fail | Proceed with daily notes + git log only |

## Step 4: Cross-Reference and Draft

### Accountability Check (when previous report exists)

Compare last week's 「下周工作计划」 against this week's actual output:

| Last week planned | This week status | How to handle |
|---|---|---|
| Completed | Done | Include in 本周总结 |
| Partially done | In progress | Note progress in 本周总结, carry forward to 下周计划 |
| Not started | Missed | Flag in 其他事项 with reason if known |
| Unplanned work done | New | Add to 本周总结 as new item |

### Project Grouping

Do not hardcode groups. Instead, derive grouping from:

1. **Previous report** (if exists): reuse the same project display names and grouping
2. **Schedule YAML `title` field**: use as display name
3. **Common sense merging**: repos under the same `~/code//` that share a
   schedule can be grouped together

Omit projects with zero activity this week.

### Draft Generation

Generate three sections following [report-template.md](references/report-template.md).

**本周工作总结:**

- Group by project, each header includes phase progress (e.g., `进度 4/6`) when available
- Each project 1-2 bullets max, compress into core deliverables
- Each bullet: `**bold key phrase**：` + business-language description
- Use domain numbers (接口数、页面数、参数个数), NOT internal numbers (commit 数、PR#)
- Skip entirely: CI/CD changes, version bumps, SDK sub-releases, upstream open-source contributions, internal process improvements (CLAUDE.md, openspec schema)
- sunlite and sylsmart are separate projects — never merge them

**下周工作计划:**

- Source from schedule YAML next-week modules + carry-forward items
- Include time estimates when known (e.g., `（2.5 天）`)
- Each bullet: `**bold key phrase**：` + expected outcome in business terms
- sunlite and sylsmart must have separate headers with separate time allocations

**其他事项:**

- Carry-forward items from last week's plan that didn't get done, with brief reason
- Handoffs, blockers, cross-team coordination
- Keep it concise — no technical explanations in parentheses

## Step 5: User Review and Write

1. Present the full draft
2. Wait for user feedback
3. Apply changes — important: if user doesn't mention an item, it's fine as-is, do NOT remove it
4. Write final version to the daily note under `## 2 Work Log`

## Step 6: Schedule Next Week

After the report is written, parse the 「下周工作计划」 section and create Calendar events
and Reminders for next week. This closes the loop — what you wrote in the plan becomes
actionable items on your schedule.

### Parse Plan Items

From each bullet in 下周工作计划, extract:

- **Task name**: the bold key phrase
- **Project**: the project header it belongs to
- **Time estimate**: if `（N 天）` is specified

### Create Reminders

First check available lists with `reminders show-lists`, then create items in an
appropriate list (prefer "提醒" or the first available work-related list):

```bash
reminders add "提醒" "{project}: {task name}" --due-date "next monday"
```

If a task has a specific day mentioned (e.g., "周三前完成"), use that date instead.

### Create Calendar Time Blocks (optional)

If time estimates are available per project, suggest Calendar time blocks.
Calculate actual next-week dates (not relative offsets) to ensure accuracy:

```bash
# Example: create a time block for next Monday (2026-03-16) 9:00-17:00
osascript -e '
tell application "Calendar"
    tell calendar "工作"
        set startDate to date "2026年3月16日 09:00:00"
        set endDate to date "2026年3月16日 17:00:00"
        make new event with properties {summary:"sylsmart: auth 接口适配", start date:startDate, end date:endDate}
    end tell
end tell'
```

### Defaults

- **Calendar name**: "Work " (note trailing space) (with trailing space — verify with `osascript -e 'tell application "Calendar" to get name of calendars'`)
- **Time block**: 9:30-11:45 (morning focus block, not full day)
- **No all-day events**: Always create timed events, never all-day
- **Reminders list**: `提醒`

### Date calculation

Use `current date` with day offsets to calculate next week's dates. Do not use
hardcoded date strings — they cause locale-dependent parse errors on macOS.

```applescript
set baseDate to current date
set time of baseDate to 0
set nextMon to baseDate + ({offset} * days)
set startTime to nextMon + (9 * hours) + (30 * minutes)
set endTime to nextMon + (11 * hours) + (45 * minutes)
```

Present the proposed schedule to the user first — only create after confirmation:

```text
下周日程建议（Work 日历，9:30-11:45）：
  周一 3/23: sylsmart - xxx（1 天）
  周二-周三 3/24-3/25: sunlite - xxx（2 天）
  周四 3/26: HA 集成 - xxx（1 天）
  周五 3/27: buffer / 周报

确认创建到 Calendar 和 Reminders 吗？
```

## Important Behaviors

**Do not remove items the user didn't mention.** During review, the user will only call out
things that need changing. Silence means approval. This is a lesson learned from real usage:
removing "good" items to make room for user corrections breaks the report.

**Business language, not technical jargon.** The boss does NOT read code. Write what was
done and what it enables, using domain terms (接口、页面、配置参数、用户可以...). Never use:
implementation details (Router Factory, Playwright E2E, migration downgrade), internal process
names (CLAUDE.md, openspec review schema), version bumps (v0.2.0→v0.2.1), commit/PR counts,
or CI/CD details. These are valuable data for collection but must be translated to
business outcomes in the final report.

**Concrete with business numbers.** Use domain-relevant numbers: 14 个接口, 17 个页面,
4 个配置参数, 18 个待确认问题. NOT: 13 commits, PR#78, 91% coverage.

**Match previous report style.** If a previous report exists, mirror its voice, detail level,
and formatting choices. The goal is consistency across weeks so the boss sees a coherent
narrative, not a different writing style each time.

## Common Issues

| Issue | Fix |
|-------|-----|
| No daily notes found | Verify Obsidian vault path, check iCloud sync status |
| Schedule YAML parse error | Validate YAML syntax, check `timeline.start` date format |
| Previous report not found | Normal for first week — skip accountability check |
| `gh search` returns 0 results | Check date range format, verify `gh auth status` |
| Calendar "工作" not found | Run `osascript -e 'tell application "Calendar" to get name of calendars'` to list available calendars, use an existing one |
| Reminders list not found | Run `reminders show-lists` and use an available list |
| Git log shows upstream commits | Filter by `--author` to exclude upstream noise |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [niracler](https://github.com/niracler)
- **Source:** [niracler/skill](https://github.com/niracler/skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-niracler-skill-weekly-report
- Seller: https://agentstack.voostack.com/s/niracler
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.