Agent Skills 入门：用可复用技能包封装 AI 任务流程

my-skill/
├── SKILL.md          # 必需：技能描述、使用条件、任务流程、核心指令
├── scripts/          # 可选：可执行脚本，例如 .py、.sh、.js
├── references/       # 可选：参考文档、规则、模板、规范
└── assets/           # 可选：图片、模板文件、示例素材

---
name: pdf
description: Comprehensive PDF toolkit for extracting text and tables, merging or splitting documents, and filling forms.
license: Apache-2.0
compatibility: Requires Python 3.10+, poppler-utils, and internet access.
allowed-tools: Bash(pdftotext:*) Bash(python:*) Read
metadata:
  owner: "platform-team"
  version: "1.0.0"
---

# PDF 处理技能

当用户需要提取 PDF 文本、解析表格、拆分文档、合并文档或填写表单时，使用该技能。

## 执行规则

- 提取文本时优先使用 `scripts/extract_text.py`。
- 表格解析失败时，读取 `references/table_extraction_guide.md` 中的回退策略。
- 输出必须包含文件名、页码范围和处理结果摘要。

weekly_git_report/
├── SKILL.md
├── scripts/
│   └── fetch_git_commits.py
└── references/
    └── weekly_report_template.md

---
name: weekly_git_report
description: Generate a structured biweekly work report from recent Git commit messages across local repositories. Use this skill when the user asks for weekly report, biweekly report, work summary, Git commit summary, or project progress report.
license: MIT
compatibility: Requires git and Python 3.10+
allowed-tools: Bash(git:*) Bash(python3:*) Read
metadata:
  version: "0.1.0"
---

# 双周 Git 周报生成技能

## 能力范围

基于本地多个 Git 仓库最近 14 天的 commit message，生成结构化双周工作报告。

## 默认输入

- 默认代码父目录：`~/code`
- 如果该目录不存在，询问用户提供 Git 仓库父目录。
- 只扫描代码父目录下的一级子目录。
- 只有包含 `.git` 目录的子目录才视为 Git 仓库。

## 数据获取

使用脚本：

`scripts/fetch_git_commits.py`

脚本输出按项目分组的 commit message。执行时可以传入代码父目录：

```bash
python3 scripts/fetch_git_commits.py --parent-dir ~/code --days 14

这里有几个关键点：

- `description` 包含 `weekly report`、`biweekly report`、`Git commit summary` 等触发词，方便 Agent 匹配。
- `allowed-tools` 限制可用命令范围，避免 Skill 获得过宽权限。
- 输出规则明确要求“不凭空编造”，因为周报生成很容易被模型补充不存在的工作项。
- 模板路径和脚本路径写清楚，让 Agent 能按需加载。

### 6.3 编写 Git 提交读取脚本

`scripts/fetch_git_commits.py`：

```python
#!/usr/bin/env python3

import argparse
import subprocess
import sys
from datetime import datetime, timedelta
from pathlib import Path


def is_git_repo(path: Path) -> bool:
    """判断目录是否为 Git 仓库。"""
    return (path / ".git").is_dir()


def get_commits(repo_path: Path, days: int) -> list[str]:
    """获取指定仓库最近 N 天的非 merge commit message。"""
    since_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")

    try:
        result = subprocess.run(
            [
                "git",
                "log",
                f"--since={since_date}",
                "--pretty=format:%s",
                "--no-merges",
            ],
            cwd=repo_path,
            capture_output=True,
            text=True,
            check=True,
        )
    except subprocess.CalledProcessError as exc:
        print(f"跳过仓库 {repo_path}：git log 执行失败，{exc}", file=sys.stderr)
        return []

    output = result.stdout.strip()
    if not output:
        return []

    return [line.strip() for line in output.splitlines() if line.strip()]


def scan_repositories(parent_dir: Path, days: int) -> dict[str, list[str]]:
    """扫描父目录下一级 Git 仓库，并返回 commit message。"""
    reports: dict[str, list[str]] = {}

    if not parent_dir.exists():
        raise FileNotFoundError(f"代码父目录不存在：{parent_dir}")

    for child in sorted(parent_dir.iterdir()):
        if not child.is_dir():
            continue

        if not is_git_repo(child):
            continue

        commits = get_commits(child, days)
        if commits:
            reports[child.name] = commits

    return reports


def print_reports(reports: dict[str, list[str]]) -> None:
    if not reports:
        print("过去两周没有找到 Git 提交记录。")
        return

    for repo_name, commits in reports.items():
        print(f"### 项目：{repo_name}")
        for commit in commits:
            print(f"- {commit}")
        print()


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--parent-dir",
        default="~/code",
        help="代码仓库父目录，默认 ~/code",
    )
    parser.add_argument(
        "--days",
        type=int,
        default=14,
        help="统计最近多少天的 commit，默认 14 天",
    )

    args = parser.parse_args()
    parent_dir = Path(args.parent_dir).expanduser().resolve()

    try:
        reports = scan_repositories(parent_dir, args.days)
    except FileNotFoundError as exc:
        print(str(exc), file=sys.stderr)
        sys.exit(2)

    print_reports(reports)


if __name__ == "__main__":
    main()

# 本双周工作周报（{{start_date}} 至 {{end_date}}）

## 一、主要工作内容

按项目分组，总结最近 14 天完成的功能开发、问题修复、重构优化、测试补充、依赖升级等事项。

示例：

### 1. 项目 A

- 完成 XXX 功能开发。
- 修复 YYY 模块的空指针问题。
- 补充 ZZZ 相关单元测试。

## 二、遇到的问题与解决方案

只从 commit message 中能推断出的内容整理问题和解决方案，不要虚构。

示例：

- 问题：登录过滤器配置不完整。
  解决：更新过滤器配置，并补充相关依赖。

## 三、后续计划

如果 commit message 中无法推断后续计划，可以给出与当前工作自然衔接的待办方向，并标注为“建议”。

## 四、Git commit message 附录

保留原始 commit message，按项目分组列出，方便核对。

帮我生成近双周周报

# 本双周工作周报（2026-05-24 至 2026-06-07）

## 一、主要工作内容

### 1. order-service

- 完成订单状态同步逻辑调整。
- 修复订单取消场景下库存回滚失败的问题。
- 补充订单查询服务的单元测试。

### 2. admin-web

- 新增运营后台导出任务入口。
- 优化用户列表筛选条件。
- 升级前端构建依赖。

## 二、遇到的问题与解决方案

- 问题：订单取消后库存回滚存在遗漏。
  解决：补充取消流程中的库存回滚分支，并增加回归测试。

## 三、后续计划

- 建议继续补充订单异常状态的测试覆盖。
- 建议检查导出任务在大数据量下的执行耗时。

## 四、Git commit message 附录

### order-service

- fix(order): rollback stock when order is cancelled
- test(order): add unit tests for order query
- refactor(order): simplify status sync flow

### admin-web

- feat(export): add export task entry
- chore(deps): upgrade build dependencies

mkdir -p ~/.qoder/skills
cp -r weekly_git_report ~/.qoder/skills/

~/.qoder/skills/
└── weekly_git_report/
    ├── SKILL.md
    ├── scripts/
    │   └── fetch_git_commits.py
    └── references/
        └── weekly_report_template.md

/skills

帮我生成近双周周报，代码目录是 ~/workspace

references/
├── code_review_rules.md
├── unit_test_spec.md
├── report_template.md
└── troubleshooting.md

export CODE_PARENT_DIR=~/workspace

description: A useful report skill.

description: Generate weekly or biweekly work reports from local Git commit messages. Use when the user asks for work summary, weekly report, biweekly report, project progress, or Git commit summary.