skills/skills/worklog/README.md

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 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

./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: 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