Project Cairn skill
A skill that has the agent keep a project's log, plan and conclusions in files and move verified lessons into Obsidian, Notion or Lark
- 253 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Creates and changes project files: AGENTS.md, CLAUDE.md, .cairn/config.yaml and the cairn folder
- Graduation steps run bash and Python scripts that write to Obsidian, Notion or a Lark and Feishu wiki with your access
- You review yourself the scope of what goes into an external knowledge base
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/project-cairnDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Creates and changes project files: AGENTS.md, CLAUDE.md, .cairn/config.yaml and the cairn folder
- Graduation steps run bash and Python scripts that write to Obsidian, Notion or a Lark and Feishu wiki with your access
- You review yourself the scope of what goes into an external knowledge base
This is third-party code. Review the repository files before installing.
What it does
Project Cairn installs as a skill and teaches an agent to keep a project's knowledge inside the project. The command "Initialize Project Cairn in this project" prompts the agent to ask for a short project summary and a git policy, then create the rules and configuration. The rules live in `AGENTS.md`, which the agent reads on entering the project, so there is no separate background process. The `cairn/` folder holds `LOG.md` with short records of progress, `ROADMAP.md` with the goal, plan and progress, topic files with the current conclusion, and `Cited.md` with links to external knowledge that shaped the project. References distinguish the project’s conclusions from the external sources behind them. When a lesson fits other projects, the agent proposes it as a candidate for transfer to a shared knowledge base. The prepared notes are stripped of project detail and receive links to the original project and materials. The instructions require user approval before writing to Obsidian, Notion or a Lark and Feishu wiki. Later projects search the base first and add a pointer to `Cited.md` when a result proved useful. An audit finds contradictions, stale conclusions and missing records.
Who it is for. For people who run several projects with AI agents, switch between Claude Code and Codex, and want conclusions to outlive single sessions.
Good fit when
- The same mistake keeps coming back in new projects and a verified lesson should go into a shared knowledge base
- You switch sessions or agents and do not want to re-explain context, rules and the current plan
- Plans, progress and conclusions are scattered across old chats and the agent jumps between older and newer directions
- You want to check whether the project's records have drifted from reality, which an audit of contradictions and gaps does
- You are closing an exploration branch and want to save its knowledge from `cairn/` before the branch disappears
Not a fit when
- You want an install from a package manager: there is no packaged release, the skill is installed by cloning the repository
- You work on Windows without WSL or Git Bash: the bash scripts were verified on macOS and Linux only
- You want automatic background memory capture: the skill uses no hooks and does not fire when a chat ends
- You need memory of the agent's preferences instead of project knowledge: agent memory tools fit that
Example request
Initialize Project Cairn in this project, and after the bot fix is verified record the conclusion in cairn and suggest what is worth moving to ObsidianLimitations
There is no background memory collection or post-chat synchronization: the agent maintains files while working. Scripts need Git and Bash, some operations need Python 3, and batch Notion writes require PyYAML. The author suggests WSL or Git Bash on Windows.
Export to an external knowledge base is a separate choice. The Notion adapter uses an API token; Lark needs an authenticated CLI. Updating an existing page can replace its contents. Approval is an agent instruction, with no automatic confirmation dialog in the script. Preview the operation and save the current page before writing.
How to disable. Delete the skill folder, for example `~/.claude/skills/project-cairn` for Claude Code or `~/.agents/skills/project-cairn` for Codex. Projects keep `AGENTS.md`, `cairn/` and `.cairn/config.yaml`, which you can leave as notes or delete by hand.
FAQ
How do I install Project Cairn in Claude Code?
Run `git clone https://github.com/iBlinkQ/project-cairn.git ~/.claude/skills/project-cairn`. SKILL.md must sit at the root of the project-cairn folder, not in a nested one. Then open a new session and tell the agent "Initialize Project Cairn in this project".
How do I install Project Cairn in Codex or WorkBuddy?
For Codex clone the repository into `~/.agents/skills/project-cairn`. In WorkBuddy open Skills in the sidebar, choose Add Skill, then Upload Skill and upload the repository ZIP; no manual copying is needed.
Which files does Project Cairn create in a project?
A root `AGENTS.md` with the rules, `.cairn/config.yaml` with settings, `cairn/LOG.md`, optionally `cairn/ROADMAP.md`, topic files and `cairn/Cited.md`. The templates sit in the skill's `assets/templates/` folder.
Where does Project Cairn move knowledge and when?
Into Obsidian, Notion or a Lark and Feishu wiki. Before a write you can check installation and access with the `obsidian-preflight.sh`, `notion-preflight.sh` and `lark-preflight.sh` scripts.
What does an audit do in Project Cairn?
The audit compares notes with the current project and looks for contradictions, stale conclusions and gaps. Instructions require discussing material changes with the user; this is not a technical write barrier.
Discussion
No questions or reviews yet.
Related
SkillsA skill that cross-examines a plan before work starts: numbered questions in rounds with a recommended answer and no changes until you confirm
A skill set that lets an agent run a personal Obsidian wiki: it compiles knowledge from documents and past sessions and answers with citations
cafe3310's personal skill collection: spec-driven project work, reviews, reports, browser, 3D and video in one repository
A skill that keeps project memory in plain Markdown files: session logs, a wiki, rules, a to-do list and a note on where to resume
A plugin that files PDFs, slides and links into Obsidian notes and proposes edits to its own rules after every run
An agent saves web pages, PDFs and scans into a local vault, builds linked concepts and answers from them with source references.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Project Cairn (this card) | no | 253 | |
| LLM Wiki | no | 1,509 | a wiki compiled from sources you have read, while Cairn keeps knowledge learned while working on a project |
| Citadel | no | 927 | an operating layer with a /do entry point and project memory, with no graduation of lessons into Obsidian, Notion or Lark |
README in short
The collection uses MIT. Project templates and knowledge-base adapters are separate, so local notes can be maintained without Notion or Lark.
README badge
Original SKILL.md
---
name: project-cairn
description: Standardize how an AI-collaboration project turns work into reusable knowledge. Use when initializing or retrofitting Project Cairn in a project, recording progress after meaningful work, maintaining AGENTS/CLAUDE/cairn docs, auditing project knowledge for drift or missing records, pulling and citing external knowledge, or graduating validated project experience into a reusable knowledge base.
---
# Project Cairn
Project Cairn gives AI-collaboration projects a durable way to keep and reuse what they learn while doing real work. The **Skill** supplies the method, **AGENTS.md** carries always-read project rules, and **`.cairn/config.yaml`** stores machine-readable configuration.
This Skill is documentation-first. It provides instructions, templates, references, and provider adapters. It has no CLI, MCP server, background hook, chat-end trigger, automatic provider write, or automatic history migration. Routine maintenance happens during normal work because `AGENTS.md` carries the rules. Provider writes require human confirmation.
## Routing
Load exactly the reference you need:
- `references/init.md` — initialize, retrofit, bootstrap, or set up Project Cairn in a project.
- `references/consume.md` — pull, cite, reuse, or apply external knowledge from the configured knowledge base.
- `references/maintenance.md` — record progress, update LOG, update ROADMAP, maintain topic notes, or apply Cairn rules after work.
- `references/audit.md` — inspect, audit, validate, clean up, or find missing project knowledge records.
- `references/upgrade.md` — upgrade an initialized project instance to the current skill spec, or check how far it has drifted (instance drift after the skill itself evolved).
- `references/graduation.md` — graduate knowledge, move reusable experience to a knowledge base, or judge graduation-readiness; a provider write additionally reads only the selected `references/graduation/<provider>.md`.
- `references/frontmatter.md` — create or review Cairn topic notes or knowledge-base notes.
- `references/branch-closure.md` — review, close, abandon, or roll back an exploration branch and salvage its `cairn/` knowledge before it disappears.
- `references/zh-glossary.md` — writing project docs in Chinese (or resolving what a Chinese term should be); fixed English↔Chinese terminology mapping for Project Cairn's own vocabulary.
Frontmatter describes triggers, not workflow.
## Templates
`assets/templates/` contains `AGENTS.md`, `CLAUDE.md`, `config.yaml`, `user-config.yaml`, `LOG.md`, `ROADMAP.md`, `topic.md`, and `Cited.md`. `init` scaffolds `AGENTS.md`, `CLAUDE.md`, `.cairn/config.yaml`, `cairn/LOG.md`, and optional `cairn/ROADMAP.md`; it can seed optional `~/.config/cairn/config.yaml` from `user-config.yaml`. `topic.md`, `Cited.md`, and `Reference/` are trigger-created. Templates use `{{PLACEHOLDER}}` tokens; never hardcode a provider or knowledge path.
## Boundaries
- No background hook and no chat-end trigger are assumed.
- Day-to-day maintenance happens because `AGENTS.md` is read as project rules.
- Audit is the safety net for missed records.
- Graduation is candidate detection plus human confirmation.
- Historical migration is optional and separate from init.
- `scripts/*.sh` use bash (verified on macOS/Linux; Windows needs WSL or Git Bash). `scripts/*.py` use Python 3 without a shell; `notion-graduate-batch.py` also needs PyYAML.