Automating Weekly Work Reports with Agent Skills: A Complete Implementation Guide

Background: The Weekly Report Pain Point

Every Monday, the same ritual unfolds: recalling what you accomplished last week means scrolling through git logs, piecing together Jira links, and translating technical work into human-readable prose. Half an hour disappears just like that. The bigger problem? If these records aren't organized promptly, when year-end summary time arrives, you can't remember what you've done at all.

Wanting to solve this problem, but not wanting to manually tell AI "help me look at these commits and write a weekly report" every time, led to implementing an Agent Skill: /weekly-report.

Effect Demonstration

In the work-journal directory, simply input:

/weekly-report

The system automatically scans last week's commits across all git repositories, generates a Chinese weekly report, and commits it:

Weekly Report Example:

xxx-ecom:围绕 TO-xxxx 对 admin 后台的交易和订阅 API 做了一轮字段扩展与重构。新增 xxx 字段到 xxx 和 xxx 接口，去掉了 xxx 前缀的冗余命名，并将 xxx.xxx 的参数整合为 xxx 对象以提升可读性。后续又修正了 xxx 字段在取消订阅场景下不必要的返回逻辑，统一了 snake_case 命名风格。

xxx-portal-bff: 同属 TO-xxxx，修复了 Jenkins 流水线中 CodeArtifact token 获取失败的问题，将 OpenJDK 基础镜像版本钉死到 17.0.2 以避免构建漂移；重构了 pipeline 的 compile 和 build 函数，拆出独立的 update_dependency 阶段，避免重复获取 token，并在 build 脚本中跳过不必要的 dependency check 以提速。

xxx-backend-service: TO-xxxx 后端侧同步扩展：在 xxx API 响应中新增 xxx 字段，在 xxx API 响应中新增 xxx 字段，同时清理了 xxx 中多余的 xxx 映射逻辑。

xxx-portal-web: TO-xxxx 前端侧：在 B2C 客户页面的 xxx 列表中添加 xxx 可点击跳转；xxx 和 xxx 页面通过 router state 传递 xxx，实现从客户页面跳转后自动展开对应套餐导航；修复若干 ESLint 问题。

xxx-mobile-app: TO-xxxx 修复了 NewYearPromotion202512 促销活动的背景图片显示问题。

The report segments by repository, automatically converts Jira numbers to complete links, and once written, commits directly into the work-journal repository.

You can also retroactively generate historical weekly reports:

/weekly-report 2026-03-29

Implementation Approach

Source code: github.com/zhaokang555/kang-skills

The Agent Skill consists of four files:

SKILL.md: The Orchestration Layer

SKILL.md serves as the entire process's orchestration layer, composed of frontmatter (name, description, and other metadata) and several numbered steps. Steps mix two types of instructions that AI executes in sequence:

Bash instructions call scripts to handle deterministic logic. For example, calculating dates, scanning commits—these matters with fixed answers are entirely outsourced to scripts:

node .claude/skills/weekly-report/collect-commits.js <Monday> <Sunday> <email>

Prose instructions tell AI how to generate. For example, "segment by repository, convert Jira numbers to complete URLs, write in technical log style that engineers write for themselves six months later"—after AI receives clean data output from scripts, it generates final text according to these rules.

The boundary between these two instruction types is "deterministic versus generative": matters with fixed answers (dates, commit lists) are written as scripts; those requiring understanding and expression (summarizing commits into human language) are written as prompts.

config.json: Personal Path Storage

Personal paths are stored separately, not committed into the code repository:

{
  "scanDir": "/path/to/your/repos",
  "jiraBaseUrl": "https://yourcompany.atlassian.net/browse"
}

config.json is added to .gitignore, while providing config.example.json as a template open-sourced along with the code.

calc-dates.js: Precise Date Calculation

Date calculation cannot rely on AI mental arithmetic—time zones and week boundaries are too error-prone. A dedicated script handles this matter:

// calc-dates.js [YYYY-MM-DD]
// No parameters: returns last week's Monday and Sunday; with parameters: verify it's Sunday, return that week's Monday and Sunday
node .claude/skills/weekly-report/calc-dates.js
// → {"monday":"2026-03-30","sunday":"2026-04-05"}

When parameters aren't Sunday, it directly errors and exits. SKILL.md simply transfers error messages to the user.

collect-commits.js: Structured Commit Collection

Having AI directly extract commits from git log consumes many tokens and has poor stability (output format isn't fixed). Therefore, this logic is extracted into a Node.js script, called by SKILL.md:

// collect-commits.js <MONDAY> <SUNDAY> <AUTHOR_EMAIL>
// Scans all git repositories under BASE_DIR (maximum depth 3), outputs commit records within specified period
const repos = run(`find ${BASE_DIR} -maxdepth 3 -name ".git" -type d -prune`)

for (const repo of repos) {
  const hashes = run(
    `git -C "${repo}" log --format="%H" --no-merges ` +
    `--after="${monday} 00:00:00" --before="${sunday} 23:59:59" ` +
    `--author="${author}"`
  )
  // ...
}

The script outputs structured text (=== REPO: xxx === / --- COMMIT ---). AI receives clean data, saving tokens and avoiding errors from git output format changes.

The SKILL.md + scripts combination proves far more stable than pure SKILL.md (having AI directly run git commands and parse output).

Scheduled Tasks: Making Weekly Reports Truly Automated

Manually entering commands once a week still creates friction. Different systems have different scheduling tools. Taking macOS as an example, you can use the built-in launchd to automatically trigger every Monday morning.

Creating a launchd Job

Create a plist file at ~/Library/LaunchAgents/com.yourname.weekly-report.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.yourname.weekly-report</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/weekly-report-runner.sh</string>
    </array>
    <key>StartCalendarInterval</key>
    <dict>
        <key>Weekday</key>
        <integer>1</integer>
        <key>Hour</key>
        <integer>9</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
    <key>WorkingDirectory</key>
    <string>/path/to/work-journal</string>
    <key>StandardOutPath</key>
    <string>/tmp/weekly-report.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/weekly-report.err</string>
</dict>
</plist>

Load the job:

launchctl load ~/Library/LaunchAgents/com.yourname.weekly-report.plist

Linux Alternatives: cron or systemd

For Linux systems, use cron:

# Edit crontab
crontab -e

# Add this line to run every Monday at 9 AM
0 9 * * 1 /path/to/weekly-report-runner.sh >> /tmp/weekly-report.log 2>&1

Or create a systemd timer for more robust scheduling with logging and failure handling.

Windows Task Scheduler

Windows users can create a scheduled task through Task Scheduler GUI or PowerShell:

$action = New-ScheduledTaskAction -Execute "wsl" -Argument "-e bash -c '/path/to/weekly-report-runner.sh'"
$trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Monday -At 9am
Register-ScheduledTask -TaskName "WeeklyReport" -Action $action -Trigger $trigger

Advanced Features and Customization

Multi-User Support

For team environments, extend the skill to support multiple authors:

// In collect-commits.js
const authors = config.authors || [getDefaultEmail()];

for (const author of authors) {
  // Collect commits for each author
  // Generate separate sections or merged report
}

Custom Report Templates

Create organization-specific report templates:

{
  "template": "executive-summary",
  "sections": ["accomplishments", "blockers", "next-week-plans"],
  "includeMetrics": true,
  "jiraIntegration": true
}

Integration with Project Management Tools

Extend beyond git to include:

Jira ticket status changes
Pull request reviews completed
Documentation updates
Meeting notes summaries

Best Practices and Lessons Learned

Start Simple, Iterate Quickly

Begin with basic git commit scanning. Once that works reliably, add Jira integration. Then add scheduling. Then add customization options. This incremental approach ensures each layer works before adding complexity.

Handle Edge Cases Gracefully

Common edge cases to handle:

No commits in the time period (generate empty report with note)
New repository added mid-week (include partial week data)
Holiday weeks with fewer working days (adjust expectations accordingly)
Merge commits and rebases (filter or include based on preference)

Maintain Clear Separation of Concerns

Keep deterministic logic in scripts, generative logic in prompts. This separation makes debugging easier and reduces token consumption.

Document Everything

Maintain clear documentation for:

Installation steps
Configuration options
Troubleshooting common issues
Extension points for customization

Measuring Success: The Real Impact

After implementing this system, track these metrics:

Time saved per week: Typically 30-45 minutes
Report consistency: Standardized format improves readability
Historical record completeness: No more forgotten accomplishments
Year-end summary preparation time: Reduced from days to minutes

One user reported: "30 minutes to set up, zero handwritten weekly reports for the entire year. At year-end, throw all 52 weekly reports to AI,配合 Atlassian/Jira skill/MCP, 10 minutes to produce year-end summary."

Conclusion: Automation That Actually Works

The /weekly-report Agent Skill demonstrates a fundamental principle: effective automation combines deterministic scripts for reliable data collection with AI's generative capabilities for human-readable output. Neither approach alone suffices—scripts without AI produce dry data dumps; AI without scripts produces inconsistent, token-expensive results.

By respecting this boundary and building a system that leverages each technology's strengths, you create automation that genuinely saves time rather than creating new maintenance burdens. The result: weekly reports that write themselves, leaving you free to focus on the actual work worth reporting.

The source code remains openly available, inviting community contributions and adaptations for different workflows. Because the best automation tools aren't those that work perfectly for one person—they're those that can be adapted to work well for many.