forked from Zhubei_iXD/report_skill_expm
184 lines
5.8 KiB
Markdown
184 lines
5.8 KiB
Markdown
# Report Generation Skills Experiment
|
||
|
||
This repository contains AI skills for automated report generation. Currently includes a weekly project report generator that transforms time tracking data into formatted management reports.
|
||
|
||
## Available Skills
|
||
|
||
### 📊 Week Report Generator (`week_report_gen`)
|
||
|
||
Automatically generates weekly project reports (項目週報) from exported Excel time tracking data.
|
||
|
||
**Features:**
|
||
- Reads cost report Excel exports from project management systems
|
||
- Aggregates work hours by person and project
|
||
- Generates formatted weekly reports following company templates
|
||
- Auto-populates team members, work hours, and progress notes
|
||
- Creates professional Excel output with proper formatting
|
||
|
||
**Use Cases:**
|
||
- Weekly project status reporting
|
||
- Time tracking data transformation
|
||
- Team productivity summaries
|
||
- Management reporting automation
|
||
|
||
**Quick Start:**
|
||
```bash
|
||
cd skills/week_report_gen
|
||
python generate_report.py
|
||
```
|
||
|
||
**Documentation:**
|
||
- [SKILL.md](skills/week_report_gen/SKILL.md) - Comprehensive skill documentation
|
||
- [README.md](skills/week_report_gen/README.md) - Usage guide and examples
|
||
- [QUICK_REFERENCE.md](skills/week_report_gen/QUICK_REFERENCE.md) - AI assistant reference
|
||
|
||
## Getting Started
|
||
|
||
### Prerequisites
|
||
|
||
```bash
|
||
# Create virtual environment and install dependencies
|
||
uv sync
|
||
|
||
# Activate virtual environment (optional - uv run handles this)
|
||
.venv\Scripts\activate # Windows
|
||
source .venv/bin/activate # Linux/Mac
|
||
```
|
||
|
||
> **💡 Tip**: This project uses `pyproject.toml` for reliable dependency management with uv.
|
||
> See [UV_SETUP_GUIDE.md](UV_SETUP_GUIDE.md) for detailed setup instructions and best practices.
|
||
|
||
### Using with AI Assistants
|
||
|
||
Simply tell your AI assistant (GitHub Copilot, Claude, etc.):
|
||
|
||
> "Generate a weekly report from the cost report file"
|
||
|
||
The AI will automatically:
|
||
1. Read the skill documentation
|
||
2. Process the input data
|
||
3. Generate a formatted report
|
||
4. Show you a summary
|
||
|
||
### Manual Usage
|
||
|
||
```python
|
||
from skills.week_report_gen.generate_report import generate_weekly_report
|
||
|
||
# Generate report
|
||
output_file, summary = generate_weekly_report(
|
||
input_file='path/to/cost-report.xls',
|
||
output_file='path/to/weekly-report.xlsx'
|
||
)
|
||
|
||
print(f"Report saved: {output_file}")
|
||
```
|
||
|
||
## Repository Structure
|
||
|
||
```
|
||
report_skill_expm/
|
||
├── README.md # This file
|
||
├── skills/
|
||
│ └── week_report_gen/ # Weekly report generator skill
|
||
│ ├── SKILL.md # Skill documentation
|
||
│ ├── README.md # User guide
|
||
│ ├── QUICK_REFERENCE.md # AI assistant reference
|
||
│ ├── generate_report.py # Main script
|
||
│ └── references/ # Sample files and templates
|
||
│ ├── cost-report-*.xls # Example input
|
||
│ ├── 項目週報-模板.xlsx # Standard template
|
||
│ └── 項目週報-*.xlsx # Example outputs
|
||
└── .venv/ # Virtual environment (created)
|
||
```
|
||
|
||
## Input & Output Examples
|
||
|
||
### Input: Cost Report
|
||
```
|
||
日期 使用者 活動 專案 單位
|
||
2026-01-12 ben sung Development masterXXX 8
|
||
2026-01-12 Ryan Hsueh - AXEL PLC 8
|
||
2026-01-13 傑 羅 Development CNC Library 移植 4
|
||
```
|
||
|
||
### Output: Weekly Report
|
||
```
|
||
弘訊科技股份有限公司
|
||
2026年度週報(01月12日-01月16日）
|
||
|
||
專案名稱 參與人員 工時 本周主要進展
|
||
──────────────────────────────────────────────────
|
||
AXEL PLC Ryan Hsueh 48.0 -
|
||
masterXXX ben sung 15.0 Development
|
||
migrate to entry based sdo queue
|
||
CNC Library移植 傑 羅 8.0 Development
|
||
程式碼整理及重構
|
||
```
|
||
|
||
## Development
|
||
|
||
### Adding New Skills
|
||
|
||
1. Create a new directory under `skills/`
|
||
2. Add a `SKILL.md` file with comprehensive documentation
|
||
3. Implement the skill functionality
|
||
4. Add examples and tests
|
||
5. Update this README
|
||
|
||
### Testing
|
||
|
||
```bash
|
||
# Test the weekly report generator
|
||
cd skills/week_report_gen
|
||
python generate_report.py
|
||
```
|
||
|
||
## Use Cases
|
||
|
||
### 1. Weekly Team Reports
|
||
Transform time tracking exports into management-ready weekly reports automatically.
|
||
|
||
### 2. Project Status Updates
|
||
Quickly see which projects are active, who's working on them, and how many hours were invested.
|
||
|
||
### 3. Resource Allocation Analysis
|
||
Understand how team members' time is distributed across projects.
|
||
|
||
### 4. Management Reporting
|
||
Generate standardized reports for management review with minimal manual effort.
|
||
|
||
## Roadmap
|
||
|
||
Future skills being considered:
|
||
|
||
- **Monthly Summary Generator**: Aggregate weekly reports into monthly summaries
|
||
- **Project Timeline Generator**: Visualize project progress over time
|
||
- **Resource Utilization Report**: Analyze team member utilization rates
|
||
- **Cost Analysis Report**: Transform time data into cost estimates
|
||
- **Multi-team Comparison**: Compare metrics across different teams
|
||
|
||
## Contributing
|
||
|
||
Contributions welcome! To add a new skill:
|
||
|
||
1. Follow the existing skill structure
|
||
2. Provide comprehensive documentation
|
||
3. Include example files
|
||
4. Test thoroughly
|
||
5. Submit a pull request
|
||
|
||
## License
|
||
|
||
MIT License - See individual skill files for specific licensing information.
|
||
|
||
## Support
|
||
|
||
For questions or issues:
|
||
1. Check the skill-specific documentation in `skills/[skill_name]/`
|
||
2. Review example files in `references/` directories
|
||
3. Open an issue for bugs or feature requests
|
||
|
||
## Acknowledgments
|
||
|
||
This project demonstrates how AI skills can automate routine reporting tasks, saving time and reducing errors in data transformation and report generation workflows. |