Work Record Skill

English | 简体中文

A local-first Codex skill for turning natural-language work updates into a structured, traceable Markdown repository. It keeps canonical events separate from rebuildable indexes, current views, and period summaries.

This repository is an early public release distributed under the MIT License.

What it provides

• Natural-language capture without requiring a form.
• Stable event and work-item identifiers.
• Daily records as canonical facts, with derived indexes and views.
• Corrections that preserve the real timeline.
• Weekly, monthly, and quarterly summaries with source references.
• Deterministic helpers for initialization, validation, ID allocation, affected-period discovery, rebuild planning, and transaction recovery.

The skill stores its output as readable files. It does not require a database or network service.

Privacy defaults

• The starter repository contains only empty templates and synthetic examples.
• Initialization writes to a separate directory that you choose.
• No external publishing or synchronization is enabled by default.
• Generated work repositories are excluded from this repository's common local paths by .gitignore.
• Credentials and authentication secrets must never be entered into records.

Local-first is not the same as encrypted. Protect the initialized repository with appropriate device security, filesystem permissions, backups, and access controls. Review every file before publishing or attaching it to a bug report.

Requirements

• Python 3.9 or newer.
• Codex, or another agent runtime that supports SKILL.md-based skills.
• IANA timezone data supplied by the operating system or the first-party tzdata package. Windows commonly needs python -m pip install tzdata.
• No other third-party Python packages are required by the included command-line helpers.

Install the skill

Clone this repository using the URL shown by GitHub's Code button. From the cloned repository, copy the skill directory into your personal Codex skills directory:

mkdir -p ~/.codex/skills
cp -R skills/work-record ~/.codex/skills/work-record

If ~/.codex/skills/work-record already exists, move or remove that old copy before installing the new one so stale files are not retained.

You can also keep the repository anywhere and point an agent directly to skills/work-record/SKILL.md.

Initialize a work repository

From the cloned repository:

python3 skills/work-record/scripts/init_repository.py ~/work-record \
  --timezone Asia/Shanghai \
  --language zh-CN

The initializer refuses to populate a non-empty destination by default. --force is conservative: it adds missing starter files but does not overwrite existing files. It also refuses destinations that overlap the installed Skill source tree. On POSIX systems, newly created directories use mode 0700 and new files use mode 0600; existing permissions are preserved by --force. Adjust those permissions explicitly if the repository is intentionally shared. Add --json when machine-readable output is useful.

Validate the initialized repository:

python3 skills/work-record/scripts/work_record.py validate ~/work-record --json

Then open ~/work-record as your workspace and ask the agent naturally, for example:

Record that I reviewed the rollout checklist today and identified two open risks.

See examples/README.md for a short, fully synthetic walkthrough.

Command-line helpers

The main helper is:

python3 skills/work-record/scripts/work_record.py --help

It includes commands for validation, allocating the next identifier, finding affected periods, planning derived-view rebuilds, and managing recoverable transactions. The agent workflow remains the primary interface; the commands provide deterministic checks for operations that should not depend on prose interpretation.

Run the tests

python3 -m unittest discover -s tests -p "test_*.py" -v

The continuous-integration workflow runs the unit tests on supported Python versions, initializes and validates a fresh demo repository, and checks the skill frontmatter.

Repository layout

.
├── skills/
│   └── work-record/
│       ├── SKILL.md
│       ├── agents/
│       ├── assets/starter/
│       ├── references/
│       └── scripts/
├── examples/
├── tests/
└── .github/workflows/

Security and privacy issues should be reported using the private process in SECURITY.md, not with sensitive content in a public issue.

License

Released under the MIT License.