# Worklog Skill

A skill for creating comprehensive, structured worklogs of development sessions.

## What This Skill Does

Automatically creates detailed org-mode worklogs documenting:
- Session accomplishments and decisions
- Problems encountered and solutions found
- Technical details and code changes
- Process insights and learnings
- Context for future work

## Installation

### Claude Code

```bash
# Link skill to Claude Code skills directory
ln -s $(pwd)/skills/worklog ~/.claude/skills/worklog
```

Or via Nix Home Manager:
```nix
home.file.".claude/skills/worklog" = {
  source = /path/to/skills/skills/worklog;
  recursive = true;
};
```

### OpenCode

```bash
# Link skill to OpenCode skills directory
ln -s $(pwd)/skills/worklog ~/.config/opencode/skills/worklog
```

Or via Nix Home Manager:
```nix
home.file.".config/opencode/skills/worklog" = {
  source = /path/to/skills/skills/worklog;
  recursive = true;
};
```

Ensure the opencode-skills plugin is enabled in `~/.config/opencode/config.json`:
```json
{
  "plugin": ["opencode-skills"]
}
```

## Usage

Simply ask Claude or OpenCode in natural language:

- "Document today's work"
- "Create a worklog"
- "Write a worklog for this session"
- "Log what we accomplished"
- "Record this work session"

The agent will automatically invoke this skill based on the description.

## How It Works

**Model-Invoked**: The agent decides when to activate this skill based on your request. You don't need to explicitly call it.

**Process**:
1. Gathers git context (status, commits, diffs)
2. Extracts session metrics using helper scripts
3. Loads the markdown template
4. Searches for related previous worklogs
5. Fills in all sections with session details
6. Saves to `docs/worklogs/YYYY-MM-DD-{topic}.org`

## File Structure

```
worklog/
├── SKILL.md                      # Skill definition and instructions
├── README.md                     # This file
├── assets/
│   └── worklog-template.md       # Markdown template structure
├── scripts/
│   ├── extract-metrics.sh        # Extract git statistics
│   ├── suggest-filename.sh       # Generate descriptive filename
│   └── find-related-logs.sh      # Search previous worklogs
└── examples/
    └── example-worklog.org       # Example of filled template
```

## Requirements

### System Requirements
- Must be in a git repository
- Git commands available in PATH
- Bash for helper scripts

### Project Structure
- Creates `docs/worklogs/` directory if it doesn't exist
- Worklogs saved as: `docs/worklogs/YYYY-MM-DD-{topic}.org`

### Output Format
- Org-mode (.org) format
- Structured with frontmatter metadata
- Comprehensive sections (see template)

## Helper Scripts

All scripts use absolute paths and can be tested independently:

### Extract Metrics
```bash
./scripts/extract-metrics.sh
```
Outputs: commits made today, files touched, lines added/removed

### Suggest Filename
```bash
./scripts/suggest-filename.sh
```
Analyzes recent commits to suggest descriptive filename

### Find Related Logs
```bash
./scripts/find-related-logs.sh "keyword1 keyword2"
```
Searches previous worklogs by keywords

## Testing

### Test Scripts Locally
```bash
# Test each script from the skill directory
./scripts/extract-metrics.sh
./scripts/suggest-filename.sh
./scripts/find-related-logs.sh "test search"
```

### Test Skill with Agent
1. Deploy the skill
2. In a git repository, ask: "Document today's work"
3. Verify agent creates worklog in `docs/worklogs/`

## Known Limitations

- **Git dependency**: Must be in a git repository
- **Hardcoded paths**: Assumes `docs/worklogs/` directory structure
- **Format**: Outputs markdown
- **Language**: Scripts assume bash and standard Unix tools

## Future Work

**Semantic Compression**: The worklogs are designed as raw material for a planned semantic compression workflow that will:
- Distill key insights from verbose logs
- Create searchable index of decisions and solutions
- Build knowledge graph across sessions

This workflow is not yet implemented but referenced in the worklog metadata.

## Troubleshooting

### Skill doesn't activate
- Ensure deployed: `ls ~/.claude/skills/worklog/SKILL.md`
- Try explicit language: "create a worklog"
- Check agent sees the skill in available skills list

### Scripts fail
- Verify you're in a git repository: `git status`
- Check scripts are executable: `ls -la ./scripts/`
- Test scripts individually from command line

### Directory doesn't exist
- Agent should create `docs/worklogs/` automatically
- Or manually: `mkdir -p docs/worklogs/`

### No commits to analyze
- Scripts handle repos with no commits (will show zeros)
- Filename suggestion falls back to "work-session" if no commits

## License

MIT
