Background: The Pain Points of Weekly Reports

Every Monday arrives with the same ritual: trying to recall what you accomplished last week. You dig through git logs, piece together Jira links, and polish everything into coherent language. Half an hour disappears just like that. The bigger problem is that if these records aren't organized promptly, when year-end summary time comes around, you fundamentally can't remember what you've done throughout the year.

You want to solve this problem, but you don't want to manually tell AI every time, "Help me look at these commits and write a weekly report." That's why I implemented an Agent Skill: /weekly-report.

Effect Demonstration

In the work-journal directory, simply input:

/weekly-report

The system automatically scans all git repository commits from last week, generates a Chinese weekly report, and commits it:

xxx-ecom: Around TO-xxxx, performed a round of field expansion and refactoring on the admin backend's transaction and subscription APIs. Added the xxx field to the xxx and xxx interfaces, removed the redundant xxx prefix naming, and consolidated xxx.xxx parameters into an xxx object to improve readability. Subsequently corrected unnecessary return logic for the xxx field in unsubscribe scenarios and unified the snake_case naming style.

xxx-portal-bff: Also part of TO-xxxx, fixed the CodeArtifact token acquisition failure in the Jenkins pipeline, pinned the OpenJDK base image version to 17.0.2 to avoid build drift; refactored the pipeline's compile and build functions, extracted an independent update_dependency stage to avoid repeated token acquisition, and skipped unnecessary dependency checks in the build script to speed up the process.

xxx-backend-service: TO-xxxx backend-side synchronization expansion: Added xxx field to xxx API responses, added xxx field to xxx API responses, and cleaned up redundant xxx mapping logic in xxx.

xxx-portal-web: TO-xxxx frontend-side: Added xxx clickable jump in the xxx list on the B2C customer page; xxx and xxx pages pass xxx through router state, achieving automatic expansion of corresponding package navigation after jumping from the customer page; fixed several ESLint issues.

xxx-mobile-app: TO-xxxx Fixed the background image display issue for the NewYearPromotion202512 promotional campaign.

The report is segmented by repository, Jira numbers are automatically converted to complete links, and once written, it's directly committed into the work-journal repository.

You can also regenerate 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

SKILL.md serves as the orchestration layer of the entire workflow, composed of frontmatter (metadata like name, description, etc.) and several numbered steps. The steps mix two types of instructions that AI executes in sequence:

Bash instructions call scripts to handle deterministic logic. For example, calculating dates and scanning commits—things with fixed answers—are all outsourced to scripts:

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

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

The boundary between these two instruction types is "deterministic vs. generative": Things with fixed answers (dates, commit lists) go into scripts; things requiring understanding and expression (summarizing commits into human language) go into prompts.

config.json

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

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

Add config.json to .gitignore while providing config.example.json as a template to open source alongside the code.

calc-dates.js

Date calculation cannot rely on AI mental arithmetic—time zones and week boundaries are too easy to get wrong. A dedicated script handles this:

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

If the parameter isn't Sunday, it exits with an error directly. SKILL.md simply converts the error message to the user.

collect-commits.js

It's very token-consuming and unstable for AI to directly extract commits from git log (output format isn't fixed). So 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 (max depth 3), outputs commit records within the 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 combination of SKILL.md + scripts is much more stable than pure SKILL.md (letting AI directly run git commands and parse output).

Scheduled Tasks: Making Reports Truly Automated

Manually entering the command 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.

Summary

Thirty minutes to set up, zero handwritten weekly reports for the entire year. Accumulated weekly, at year-end you can throw all 52 weekly reports to AI, combined with atlassian/jira skill/mcp, and generate a year-end summary in 10 minutes.

This approach fundamentally transforms how developers handle one of the most tedious recurring tasks. Instead of spending mental energy reconstructing what you did last week, the system automatically captures, organizes, and presents your work in a clear, professional format. The key insight is separating deterministic operations (which belong in scripts) from generative tasks (which benefit from AI's language capabilities).

The beauty of this solution lies in its sustainability. Many automation attempts fail because they require ongoing maintenance or don't integrate smoothly into existing workflows. This Agent Skill, once configured, runs with minimal intervention while producing consistently useful output that serves both immediate needs (weekly reporting) and long-term value (year-end summaries, performance reviews, project retrospectives).