project-with-reflect

English | 中文

A self-distilling meta-skill for Codex, Claude Code, Kimi Code, and other AI coding agents. — Neil Z. Shao

Best used with Obsidian + plugins:

• Neat File Tree — a cleaner, calmer file tree.
• Folder Notes — the <folder>/<folder>.md folder-note convention this skill optionally leans on (experiment records, evals, the per-workstream goal log).

Companion skills, same philosophy (a few statements carry everything, 纲举目张):

• grounding-rules — read a system through its load-bearing few: 5 to 12 rules that settle a design question in one line.
• coding-by-contract — write a system by contract: the few rules every change is held to, changed only on purpose.

Juggling several projects at once? Need to remember how to connect to a handful of machines and services? Tired of rewriting the same long prompts and re-explaining the same project to your agent?

It manages each project for you — worktrees, logs, reflect, a growing long-term knowledge base — and everything you operate (a connection), each becoming a callable /<name> skill:

• Servers — ssh in to deploy / tail logs / run commands.
• Training boxes — GPU machines: run training / nvidia-smi, with their quirks remembered (e.g. nvidia-smi -pl 300 after a reboot).
• Devices — USB/serial flash targets (dev boards…): flash / monitor / REPL.
• APIs — HTTP/WebSocket services (only the key's env-var name on disk, never the key).
• MCP servers — used directly via their mcp__<name>__* tools.

All of it Obsidian-friendly (lessons / knowledge / dashboard are clean, readable Markdown).

At a glance

• Everything is a skill — a project, and each connection above, gets its own /<name> once registered.
• Auto-logs as you work — commits, decisions, key findings, an experiment's result, an error + its fix, jotted to the active stream.
• Native hooks preserve memory at session boundaries — load context at startup/resume, checkpoint before compaction, and re-ground after compaction; they do not inject content on every tool call.
• reflect distills itself — captures the session, then folds the log into lean, readable lessons it loads next time (and appends run results to a permanent experiment record).
• Checkin reboots from disk — before work, the agent reloads the goal/plan, progress, findings, and failed attempts from persistent files.
• Loads before acting — the agent reads existing lessons / decisions / knowledge first, so it stops re-explaining and repeating mistakes.
• Runs across agents — Claude Code has the plugin flow; Codex and Kimi Code use the skill surfaces in this repo; other agents load the same generated SKILL.md files.

Core loop: work (auto-log) → /<project> reflect (capture + distill) → lean readable lessons → better next session

Install

Elegant published install:

Claude Code has the nicest first-class marketplace flow:

/plugin marketplace add initialneil/project-with-reflect
/plugin install project-with-reflect@project-with-reflect

For Codex and other agents that support the Agent Skills installer, use the open skills CLI:

npx skills add initialneil/project-with-reflect

Codex local/dev install:

Use this when working from a checkout, or if your agent does not yet wire the skills CLI into Codex's user skill directory:

mkdir -p ~/.codex/skills
ln -sfn /path/to/project-with-reflect/.codex/skills/project-with-reflect ~/.codex/skills/project-with-reflect

Kimi Code local/dev install:

Kimi Code scans user skills from ~/.agents/skills/ (and ~/.kimi-code/skills/). Symlink the Kimi adapter:

mkdir -p ~/.agents/skills
ln -sfn /path/to/project-with-reflect/.kimi-code/skills/project-with-reflect ~/.agents/skills/project-with-reflect

Hooks are auto-log nudges in ~/.kimi-code/config.toml; doctor can repair/install them.

Kimi Work (kimi-desktop app): a separate runtime from the Kimi Code CLI. It scans user skills from <app-support>/kimi-desktop/daimon-share/daimon/skills/ — and it materializes symlinked skills into real directory copies at scan, so a symlink there silently goes stale. PWR therefore syncs copies, not links (rsync, marked .pwr-synced):

# one-time: seed the meta-skill copy (or let doctor handle everything below)
rsync -a --delete --exclude .DS_Store \
  /path/to/project-with-reflect/.kimi-code/skills/project-with-reflect/ \
  "$HOME/Library/Application Support/kimi-desktop/daimon-share/daimon/skills/project-with-reflect/"
touch "$HOME/Library/Application Support/kimi-desktop/daimon-share/daimon/skills/project-with-reflect/.pwr-synced"

Once the meta-skill is there, doctor syncs every generated project/connection/command skill into Kimi Work automatically (override the location with DAIMON_SKILLS_DIR) — re-run doctor after vault-side changes land on the machine to refresh the copies. Kimi Work has no hook surface — the auto-log nudges are Kimi Code–only; in Kimi Work the behavioral contract and reflect's capture-first backstop carry the loop.

Quick start

The daily loop is: register → check status / check in → work → log and reflect.

1. Register once

# register a project → generates the /myapp skill (Kimi Code: /skill:myapp)
/register-project myapp ~/code/myapp

# optional: register a reusable workstream — just say what it's based on
/register-workstream my-feature based on main   # → generates /myapp-my-feature

2. Check status and check in

This is the beginning of the README. Read the rest at the original. Read the full README ↗