skills/skills/worklog

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

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

Or via Nix Home Manager:

home.file.".claude/skills/worklog" = {
  source = /path/to/skills/skills/worklog;
  recursive = true;
};

OpenCode

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

Or via Nix Home Manager:

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:

{
  "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 org-mode 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
├── templates/
│   └── worklog-template.org      # Org-mode 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

./scripts/extract-metrics.sh

Outputs: commits made today, files touched, lines added/removed

Suggest Filename

./scripts/suggest-filename.sh

Analyzes recent commits to suggest descriptive filename

Find Related Logs

./scripts/find-related-logs.sh "keyword1 keyword2"

Searches previous worklogs by keywords

Testing

Test Scripts Locally

# 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: Only outputs org-mode, not markdown or plain text
• 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