@adonis0123/weekly-report 1.0.6

package/.claude-skill.json

@@ -0,0 +1,46 @@
+{
+  "name": "weekly-report",
+  "version": "1.0.6",
+  "package": "@adonis0123/weekly-report",
+  "files": {
+    "references": "references/",
+    "src": "src/"
+  },
+  "targets": {
+    "claude-code": {
+      "enabled": true,
+      "paths": {
+        "global": ".claude/skills",
+        "project": ".claude/skills"
+      }
+    },
+    "cursor": {
+      "enabled": true,
+      "paths": {
+        "global": ".cursor/skills",
+        "project": ".cursor/skills"
+      }
+    },
+    "windsurf": {
+      "enabled": false,
+      "paths": {
+        "global": ".windsurf/skills",
+        "project": ".windsurf/skills"
+      }
+    },
+    "aider": {
+      "enabled": false,
+      "paths": {
+        "global": ".aider/skills",
+        "project": ".aider/skills"
+      }
+    },
+    "custom": {
+      "enabled": false,
+      "paths": {
+        "global": ".ai-skills",
+        "project": ".ai-skills"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Skill NPM Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,453 @@
+# Agent Skill NPM Boilerplate
+
+> **Distribute AI agent skills like any other npm package**
+
+AI coding tools (Claude Code, Cursor, Windsurf) support custom "skills" - reusable instructions that extend agent capabilities. But distributing them means manual file copying, no versioning, and painful updates.
+
+**This template lets you publish skills to npm:**
+
+```bash
+# Install
+npm install -g @your-org/git-commit-helper
+
+# Update
+npm update -g @your-org/git-commit-helper
+
+# It just works - installs to ~/.claude/skills/, ~/.cursor/skills/, etc.
+```
+
+**Why this matters:** Skills become proper software artifacts with semantic versioning, dependency management, private registries, and global discovery. Same infrastructure that distributes React and Express.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Template](https://img.shields.io/badge/Template-Use%20This-brightgreen)](https://github.com/YOUR-USERNAME/agent-skill-npm-boilerplate/generate)
+
+---
+
+**Quick start:** Fork this template, edit `SKILL.md`, run `npm publish`. Your skill is now installable worldwide.
+
+**Supports:** [Claude Code](https://code.claude.com/docs/en/skills), Cursor, Windsurf, and any tool following similar skill patterns. See [MULTI-TOOL-SUPPORT.md](MULTI-TOOL-SUPPORT.md).
+
+## 💡 Why npm for Skills?
+
+Manual skill distribution requires downloading files, copying to `~/.claude/skills/`, and repeating for every update. No versioning, no dependency management, no discovery.
+
+**npm solves this:**
+
+```bash
+# Install/update/uninstall with standard commands
+npm install -g @your-org/skill-name
+npm update -g @your-org/skill-name
+npm uninstall -g @your-org/skill-name
+
+# Semantic versioning for controlled updates
+npm install @your-org/skill@^2.1.0
+
+# Project-specific skills (version-locked, committed to git)
+npm install --save-dev @your-org/skill-name
+```
+
+**Core benefits:**
+- **Version control** - Semantic versioning, upgrade/rollback easily
+- **Global distribution** - Publish once, available worldwide via npm's CDN
+- **Discoverability** - Searchable on npmjs.com
+- **Enterprise ready** - Private registries for internal skills
+- **Ecosystem integration** - Works with CI/CD, monorepos, existing tooling
+
+Skills become first-class software artifacts, using the same infrastructure as React, Express, and millions of other packages.
+
+## ✨ Features
+
+- ✅ **Official Specification**: Fully compliant with Claude Code skills format
+- ✅ **Multi-Tool Support**: Install to Claude Code, Cursor, Windsurf, and more! (See [Multi-Tool Support](MULTI-TOOL-SUPPORT.md))
+- ✅ **Smart Installation**: Auto-detects global vs project-level installation
+- ✅ **Progressive Disclosure**: Supports main SKILL.md + reference files
+- ✅ **Lifecycle Management**: Install, update, uninstall scripts included
+- ✅ **Best Practices**: Follows all recommended patterns from official docs
+- ✅ **Ready to Publish**: Just customize and publish to npm
+
+## 🚀 Quick Start
+
+### Option 1: Use as GitHub Template (Recommended)
+
+This is a **GitHub Template Repository**. The easiest way to use it:
+
+1. **Click the "Use this template" button** at the top of this repository (or [click here](https://github.com/YOUR-USERNAME/agent-skill-npm-boilerplate/generate))
+2. **Name your new repository** (e.g., `my-awesome-skill`)
+3. **Clone your new repository**:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/my-awesome-skill.git
+   cd my-awesome-skill
+   ```
+4. **Customize your skill** (see [Customization Guide](#-customization-guide))
+5. **Publish to npm**:
+   ```bash
+   npm login
+   npm publish --access public
+   ```
+
+### Option 2: Clone Directly
+
+```bash
+# Clone this repository
+git clone https://github.com/YOUR-USERNAME/agent-skill-npm-boilerplate.git my-skill
+cd my-skill
+
+# Remove git history and start fresh
+rm -rf .git
+git init
+
+# Install dependencies (for development)
+npm install
+
+# Customize your skill
+```
+
+## 📁 Project Structure
+
+```
+agent-skill-npm-boilerplate/
+├── package.json                # npm package configuration
+├── SKILL.md                   # Main skill definition (REQUIRED)
+├── .claude-skill.json         # Installation configuration
+├── install-skill.js           # Installation script
+├── uninstall-skill.js         # Uninstallation script
+├── reference.md               # Detailed documentation (optional)
+├── examples.md                # Usage examples (optional)
+├── scripts/                   # Utility scripts (optional)
+│   ├── setup.sh              # Post-install setup
+│   └── config.json.example   # Configuration template
+├── README.md                  # This file (customize for your skill)
+├── LICENSE                    # License file
+└── .gitignore                # Git ignore rules
+```
+
+## 🎨 Customization Guide
+
+### Step 1: Update package.json
+
+Replace the following placeholders:
+
+```json
+{
+  "name": "@your-org/your-skill-name",        // Change this
+  "version": "1.0.0",
+  "description": "YOUR SKILL DESCRIPTION",     // Change this
+  "author": "YOUR NAME",                       // Change this
+  "repository": {
+    "url": "YOUR-REPO-URL"                     // Change this
+  }
+}
+```
+
+**About npm scopes:**
+- Use a scope (`@your-org/skill-name`) if you want to organize skills under your organization
+- Use no scope (`skill-name`) for standalone packages
+- Popular scopes: `@your-company`, `@your-username`, or custom like `@claude-skills`
+- Scopes require configuration: `npm config set @your-org:registry https://registry.npmjs.org/`
+
+### Step 2: Update SKILL.md
+
+Edit `SKILL.md` and replace placeholders:
+
+```yaml
+---
+name: your-skill-name              # Must match directory name
+description: Your skill description here. Use when [scenarios].
+allowed-tools: Read, Bash          # Tools your skill can use
+---
+```
+
+### Step 3: Update .claude-skill.json
+
+```json
+{
+  "name": "your-skill-name",        // Must match SKILL.md name
+  "package": "@your-org/your-skill-name"
+}
+```
+
+### Step 4: Add Your Logic
+
+Edit the "Instructions" section in `SKILL.md`:
+
+```markdown
+## Instructions
+
+When the user [describes scenario]:
+
+1. **Step 1**: Do something
+2. **Step 2**: Do something else
+3. **Step 3**: Complete the task
+```
+
+### Step 5: Test Locally
+
+```bash
+# Test the installation script
+node install-skill.js
+
+# Check if installed correctly
+ls -la ~/.claude/skills/your-skill-name/
+cat ~/.claude/skills/your-skill-name/SKILL.md
+
+# Open Claude Code and verify
+# Ask Claude: "What skills are available?"
+```
+
+### Step 6: Publish to npm
+
+```bash
+# Login to npm (first time only)
+npm login
+
+# Publish your skill
+npm publish --access public
+```
+
+## 📖 Skill Development Best Practices
+
+### 1. Write Clear Descriptions
+
+The `description` field in SKILL.md is crucial - it determines when Claude uses your skill:
+
+```yaml
+# ❌ Bad: Too vague
+description: Helps with files
+
+# ✅ Good: Specific and includes trigger keywords
+description: Analyzes TypeScript files for type errors. Use when checking types, debugging TypeScript issues, or validating .ts files.
+```
+
+### 2. Use Progressive Disclosure
+
+Keep SKILL.md under 500 lines. Put detailed content in separate files:
+
+```markdown
+# In SKILL.md
+For complete API reference, see [reference.md](reference.md)
+For examples, see [examples.md](examples.md)
+```
+
+Claude will only load these files when needed, saving context.
+
+### 3. Limit Tool Access
+
+Use `allowed-tools` to restrict what your skill can do:
+
+```yaml
+# Read-only skill
+allowed-tools: Read, Grep, Glob
+
+# Can read and execute (but not modify files)
+allowed-tools: Read, Bash
+
+# Full access
+allowed-tools: Read, Edit, Write, Bash
+```
+
+### 4. Include Examples
+
+Show concrete examples in your SKILL.md:
+
+```markdown
+## Examples
+
+### Example 1: Basic Usage
+
+User asks: "Check my commit message"
+
+Claude will:
+1. Read the commit message
+2. Validate format
+3. Suggest improvements
+```
+
+## 📦 Installation Behavior
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @your-org/your-skill
+```
+
+Installs to: `~/.claude/skills/your-skill-name/`
+
+Available: Across all projects for the current user
+
+### Project-Level Installation
+
+```bash
+npm install --save-dev @your-org/your-skill
+```
+
+Installs to: `.claude/skills/your-skill-name/`
+
+Available: Only in this project (can be committed to git)
+
+### Priority Order
+
+When multiple skills exist:
+1. Enterprise (managed settings)
+2. Personal (`~/.claude/skills/`)
+3. Project (`.claude/skills/`)
+4. Plugin
+
+## How Installation and Uninstallation Work
+
+This boilerplate includes automatic installation and uninstallation scripts that run when users install or remove your skill package via npm.
+
+### Installation Process
+
+When a user runs `npm install` (or `npm install -g`) on your skill package:
+
+1. **Target Detection**: The script identifies which AI coding tools are configured for installation based on `.claude-skill.json`
+2. **Scope Prefix Handling**: Extracts the actual skill name by removing any npm scope prefix (e.g., `@your-org/skill-name` becomes `skill-name`)
+3. **Path Resolution**: For each target tool, it determines the appropriate installation location:
+   - Global installation: `~/{tool-path}/skills/` (user's home directory)
+   - Project installation: `./{tool-path}/skills/` (project root directory)
+4. **Directory Setup**: Creates the skill directory using the skill name (without npm scope prefix)
+5. **File Copying**: Copies essential files:
+   - `SKILL.md` (required) - The main skill definition
+   - Any additional files specified in `.claude-skill.json`
+6. **Compatibility Cleanup**: Removes any legacy installation paths for backward compatibility
+7. **Manifest Update**: Updates the `.skills-manifest.json` to track installed skills
+8. **Post-install Hooks**: Runs any custom setup scripts defined in `.claude-skill.json`
+
+### Uninstallation Process
+
+When a user runs `npm uninstall` (or `npm uninstall -g`) on your skill package:
+
+1. **Target Detection**: Identifies which AI coding tools were configured for the skill
+2. **Scope Prefix Handling**: Uses both the skill name (without scope prefix) and full package name (with scope prefix) for compatibility
+3. **Path Resolution**: Determines the appropriate uninstallation locations
+4. **Directory Removal**: Removes the skill directory from all configured targets:
+   - Path using skill name (primary location)
+   - Path with full package name (legacy location for compatibility)
+5. **Manifest Update**: Removes the skill entry from `.skills-manifest.json`
+6. **Best-effort Cleanup**: Continues even if some steps fail to ensure clean removal
+
+## 🔧 Advanced Features
+
+### Custom Hooks
+
+Run scripts during installation:
+
+```json
+// .claude-skill.json
+{
+  "hooks": {
+    "postinstall": "bash scripts/setup.sh"
+  }
+}
+```
+
+### Multiple Files
+
+Support rich documentation:
+
+```json
+// .claude-skill.json
+{
+  "files": {
+    "reference.md": "reference.md",
+    "examples.md": "examples.md",
+    "scripts": "scripts/"
+  }
+}
+```
+
+### Configuration
+
+Let users customize your skill:
+
+```bash
+# scripts/setup.sh
+cat > scripts/config.json <<EOF
+{
+  "option1": "default",
+  "option2": true
+}
+EOF
+```
+
+## 🐛 Troubleshooting
+
+### Skill Not Appearing
+
+```bash
+# Check installation location
+ls -la ~/.claude/skills/
+
+# Verify SKILL.md format
+cat ~/.claude/skills/your-skill/SKILL.md
+
+# Check manifest
+cat ~/.claude/skills/.skills-manifest.json
+```
+
+### Permission Errors
+
+```bash
+# Fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+
+# Or use sudo (not recommended)
+sudo npm install -g @your-org/your-skill
+```
+
+### Skill Not Triggering
+
+- Make sure the `description` includes keywords users would naturally say
+- Test by asking Claude directly: "Use the your-skill-name skill to..."
+
+## 📚 Resources
+
+- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
+- [Skills Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
+- [npm Package Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork this repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## 📄 License
+
+This template is [MIT licensed](LICENSE). Skills you create from this template can use any license you choose.
+
+## 💡 Examples
+
+Skills built with this template:
+
+- `@your-org/git-commit-helper` - Generate conventional commit messages
+- `@your-org/code-reviewer` - Automated code review assistance
+- `@your-org/test-generator` - Generate test cases from code
+
+*(Add your skill here after publishing!)*
+
+## 🙋 Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/agent-skill-npm-boilerplate/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/yourusername/agent-skill-npm-boilerplate/discussions)
+- **Documentation**: [Wiki](https://github.com/yourusername/agent-skill-npm-boilerplate/wiki)
+
+## 🌟 Show Your Support
+
+If you find this template helpful:
+- ⭐ Star this repository
+- 🐛 Report bugs
+- 💡 Suggest features
+- 📝 Improve documentation
+
+---
+
+**Made with ❤️ for the Claude Code community**

package/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: weekly-report
+description: 自动读取 Git 提交记录生成周报。用于生成工作周报、项目总结、团队协作汇报。支持多仓库汇总。
+allowed-tools: Read, Write, Bash(git:*), Bash(python:*)
+metadata:
+  author: adonis
+  version: "1.0.0"
+---
+
+# 周报生成技能
+
+自动读取 Git 提交记录，按项目分组生成结构化周报。
+
+## 功能特性
+
+- 自动读取 Git 提交记录
+- 支持多仓库汇总
+- 自动识别当前用户 (`git config user.name`)
+- 按项目分组，生成结构化周报
+- 过滤琐碎提交（typo、merge、format 等）
+- 支持添加补充说明
+- 周报统一存储在 `~/.weekly-reports/` 目录
+
+## 使用方式
+
+### 基本用法
+
+在任意 Git 项目目录中执行：
+
+```
+/weekly-report
+```
+
+### 执行流程
+
+1. **选择时间范围**
+   - 本周 (显示具体日期，如 2026-01-06 ~ 2026-01-12)
+   - 上周 (显示具体日期，如 2025-12-30 ~ 2026-01-05)
+   - 前半年 (显示具体日期，如 2025-07-13 ~ 2026-01-13)
+   - 自定义周报（输入周一日期）
+   - 自定义时间段（输入起始日期，截止到今天）
+
+   **重要**：选择时必须显示具体的日期范围，让用户确认是否正确
+
+2. **选择仓库**（如已配置多仓库）
+   - 显示已配置的仓库列表
+   - 可多选要包含的仓库
+   - 可添加当前目录为新仓库
+
+3. **添加补充内容**（可选）
+   - 输入额外的工作内容
+   - 如：参与会议、技术分享等
+
+4. **生成周报**
+   - 读取选定仓库的 Git 提交（必须覆盖所有分支/远端跟踪分支，避免漏提交）
+   - 按项目分组
+   - 过滤琐碎提交
+   - 生成 Markdown 格式周报
+   - 周报保存到 `~/.weekly-reports/{year}/week-{week}.md`
+   - 时间段报告保存到 `~/.weekly-reports/periods/{start_date}_to_{end_date}.md`
+
+## Git 提交读取（重要）
+
+为避免“只读取当前分支而漏掉其它分支（例如 `credits-lite*`）”的问题，读取提交时必须使用 `--all`（覆盖本地分支 + 远端跟踪分支），并确保截止时间包含结束日当天：
+
+```bash
+# 关键点：
+# - 用 --all 覆盖所有本地 refs（包含 remotes/origin/*）
+# - --until 用 “结束日 23:59:59” 避免漏掉结束日当天提交
+# - --author 建议用 name + email 联合匹配，避免不同身份写法漏掉本人提交
+
+AUTHOR_PATTERN="(your-name|your@email.com)"  # 或仅用你的 name/email
+git log --all \
+  --author="$AUTHOR_PATTERN" \
+  --since="$START_DATE 00:00:00" \
+  --until="$END_DATE 23:59:59" \
+  --pretty=format:"%H|%s|%an|%ad" \
+  --date=short
+```
+
+如果 `git branch -a` 看不到目标远端分支（说明本地没有对应的远端跟踪引用），需要先 `git fetch --all --prune`（在用户同意且网络可用时执行），否则无法读取到“本地不存在的分支”的提交。
+
+## 输出格式
+
+周报采用层级列表结构，**必须包含日期范围标题**，按项目分组：
+
+### 周报格式
+
+```markdown
+# 周报 (2026-01-06 ~ 2026-01-12)
+
+项目名称
+  - 主要工作点（10字以内）
+    - 补充说明（可选）
+  - 另一个工作点
+
+其他
+  - 不属于特定项目的工作内容
+```
+
+### 时间段报告格式
+
+```markdown
+# 工作总结 (2025-07-13 ~ 2026-01-13)
+
+项目名称
+  - 主要工作点（10字以内）
+    - 补充说明（可选）
+  - 另一个工作点
+
+其他
+  - 不属于特定项目的工作内容
+```
+
+### 示例输出
+
+```markdown
+# 周报 (2026-01-06 ~ 2026-01-12)
+
+project-frontend
+  - 构建工具升级改造
+  - 核心功能开发流程跟进
+    - 方案合理性优化
+  - 脚本国际化优化
+
+project-backend
+  - 自定义类型化消息渲染
+  - 断线重连流程梳理
+
+其他
+  - 新版国际化方案讨论
+```
+
+## 配置文件
+
+配置文件位于 `~/.weekly-reports/config.json`：
+
+```json
+{
+  "repos": [
+    {
+      "name": "project-a",
+      "path": "/home/user/projects/project-a"
+    },
+    {
+      "name": "project-b",
+      "path": "/home/user/projects/project-b"
+    }
+  ],
+  "default_author": "auto",
+  "output_format": "markdown"
+}
+```
+
+## 总结原则
+
+### 必须遵守
+
+- **事实导向**：只总结实际完成的工作
+- **简洁精炼**：主要工作点控制在 10 字以内
+- **重点突出**：过滤琐碎修改
+- **按项目分组**：相同项目的工作归类
+- **层级清晰**：用缩进表示从属关系
+
+### 过滤规则
+
+以下提交不会单独列出：
+- 纯格式化/代码风格调整
+- 简单的 typo 修复
+- 依赖版本小幅更新
+- Merge 提交
+- 重复性的相似提交
+
+详细格式规范见 [周报格式规范](references/WEEKLY_REPORT_FORMAT.md)