project-cairn
Standardize how an AI-collaboration project turns work into reusable knowledge. Use when initializing or retrofitting Project Cairn, recording progress, distilling process documents into topic notes, maintaining AGENTS/CLAUDE/cairn docs, auditing project knowledge or a project experience knowledge base, pulling/citing external knowledge, or graduating validated experience (including one-shot graduation without init) into a knowledge base.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/iblinkq--project-cairn)HTML
<a href="/listings/iblinkq--project-cairn"><img src="/api/listings/iblinkq--project-cairn/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Claude Code**, user-level installation:
git clone https://github.com/iBlinkQ/project-cairn.git ~/.claude/skills/project-cairn
**Codex**, user-level direct skill path:
git clone https://github.com/iBlinkQ/project-cairn.git ~/.agents/skills/project-cairn
**WorkBuddy**, import the local skill package:
1. Download the [Project Cairn ZIP](https://github.com/iBlinkQ/project-cairn/archive/refs/heads/main.zip). 2. Open Skills from the WorkBuddy sidebar. Select Add Skill, then Upload Skill. 3. Choose the downloaded ZIP file. WorkBuddy configures it automatically, so you do not need to copy it into a directory.
See the [official WorkBuddy skill guide](https://www.workbuddy.ai/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market) for the installation interface.
The skill holds the method, and the project's `AGENTS.md` carries the rules the agent keeps every turn. WorkBuddy loads that file when you open the project folder in a WorkBuddy Project for code development. For other tasks, add one line to the Project's Instructions: "Read AGENTS.md at the project root and follow it as project rules." If the project already has a `CODEBUDDY.md`, WorkBuddy reads that file instead of `AGENTS.md`, so init adds an `@AGENTS.md` import line to it.
For another skill-compatible agent, clone the repository into the directory where that agent loads skills. `SKILL.md` should sit directly at the root of `project-cairn/`, not inside another nested folder.
Prerequisites are `git`, plus `bash` for `scripts/*.sh`. The shell scripts have been verified on macOS and Linux; Windows users need WSL or Git Bash. Python scripts require Python 3; `notion-graduate-batch.py` additionally requires PyYAML. There is no package-manager release yet.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 39 lines
- ---
- name: project-cairn
- description: Standardize how an AI-collaboration project turns work into reusable knowledge. Use when initializing or retrofitting Project Cairn, recording progress, distilling process documents into topic notes, maintaining AGENTS/CLAUDE/cairn docs, auditing project knowledge or a project experience knowledge base, pulling/citing external knowledge, or graduating validated experience (including one-shot graduation without init) into a 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: 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 only the reference your task needs:
- - `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/ROADMAP, distill conclusions from dialogue or project process documents into topic notes (e.g. "整理已有经验"), or apply Cairn rules after work.
- - `references/audit.md` — check project experience (`检查项目经验`; aliases `检查知识文档` / `检查主题文档` / legacy `体检`), or the experience library (`检查经验库`, no init); respect the requested scope and propose changes before writing.
- - `references/upgrade.md` — upgrade an initialized project instance to the current skill spec, or check instance drift.
- - `references/graduation.md` — graduate knowledge, judge readiness, or run one-shot graduation without init (`经验入库` / `直接整理入库`; legacy `毕业` / `一次性毕业`, e.g. “看看这个文件夹里,有哪些经验值得存进知识库”); provider writes also read 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.
- - `references/zh-glossary.md` — writing project docs in Chinese; fixed English↔Chinese terminology mapping.
- Frontmatter describes triggers, not workflow.
- ## Templates
- `assets/templates/` holds `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`, and can seed `~/.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 path.
- ## Boundaries
- - No background hook or chat-end trigger is 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 (macOS/Linux; Windows needs WSL/Git Bash). `scripts/*.py` use Python 3; `notion-graduate-batch.py` also needs PyYAML.
README.md · README · 186 lines
- [English](README.md) | [中文](README.zh-CN.md)
- # Project Cairn
- **Turn project work into reusable knowledge.**
- [Open the interactive guide to learn more about the Skill](https://iblinkq.github.io/project-cairn/)
- [](https://iblinkq.github.io/project-cairn/)
- ## Sound familiar?
- - The same problem comes back in the next project.
- - Start a new session or switch agents, and you are explaining the context and rules all over again.
- - Plans, progress, and conclusions are scattered, so the agent keeps jumping between old and new directions.
- - You know the answer exists. It is just buried somewhere in an old chat.
- ## What Project Cairn does
- Project Cairn is an agent skill. During normal project work, it helps the agent keep validated pitfall lessons, key decisions, exploration findings, and sparks of insight inside the project. When something is genuinely reusable elsewhere, the agent can prepare it for a long-term knowledge base after you confirm it.
- 
- The files have distinct jobs:
- - `AGENTS.md` holds the rules the agent reads whenever it enters the project.
- - `cairn/LOG.md` records what happened, with short summaries and pointers.
- - `cairn/ROADMAP.md` keeps the overall goal, plan, and current progress.
- - `cairn/<topic>.md` holds the current conclusion for one subject.
- - `cairn/Cited.md` points to external knowledge that actually shaped the project, without copying its body.
- A cairn is a trail marker built by earlier travelers. The name captures the goal: let the next project see where the previous one found a safe route.
- ## Who it is for
- Project Cairn is useful when you run several AI-collaboration projects, switch between skill-compatible agents such as Claude Code and Codex, or need project knowledge to survive beyond one person's memory.
- ## Install
- **Claude Code**, user-level installation:
- ```bash
- git clone https://github.com/iBlinkQ/project-cairn.git ~/.claude/skills/project-cairn
- ```
- **Codex**, user-level direct skill path:
- ```bash
- git clone https://github.com/iBlinkQ/project-cairn.git ~/.agents/skills/project-cairn
- ```
- **WorkBuddy**, import the local skill package:
- 1. Download the [Project Cairn ZIP](https://github.com/iBlinkQ/project-cairn/archive/refs/heads/main.zip).
- 2. Open Skills from the WorkBuddy sidebar. Select Add Skill, then Upload Skill.
- 3. Choose the downloaded ZIP file. WorkBuddy configures it automatically, so you do not need to copy it into a directory.
- See the [official WorkBuddy skill guide](https://www.workbuddy.ai/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market) for the installation interface.
- The skill holds the method, and the project's `AGENTS.md` carries the rules the agent keeps every turn. WorkBuddy loads that file when you open the project folder in a WorkBuddy Project for code development. For other tasks, add one line to the Project's Instructions: "Read AGENTS.md at the project root and follow it as project rules." If the project already has a `CODEBUDDY.md`, WorkBuddy reads that file instead of `AGENTS.md`, so init adds an `@AGENTS.md` import line to it.
- For another skill-compatible agent, clone the repository into the directory where that agent loads skills. `SKILL.md` should sit directly at the root of `project-cairn/`, not inside another nested folder.
- Prerequisites are `git`, plus `bash` for `scripts/*.sh`. The shell scripts have been verified on macOS and Linux; Windows users need WSL or Git Bash. Python scripts require Python 3; `notion-graduate-batch.py` additionally requires PyYAML. There is no package-manager release yet.
- ## Start in three steps
- 1. Ask the agent to "Initialize Project Cairn in this project." It will collect the project summary, git policy, and migration choice, then create the rules and configuration. Connecting a knowledge-base provider can be deferred until the first graduation.
- 2. Keep working normally. During ordinary collaboration turns, the agent follows `AGENTS.md` to maintain progress and current conclusions. There is no separate recording service to run.
- 3. When a validated lesson could help another project, ask the agent to prepare a graduation candidate. Nothing is written to the long-term knowledge base until you confirm the scope. Later projects search first and add a pointer to `cairn/Cited.md` only when a result actually influences the work.
- Already have an ongoing project or a finished project folder?
- - **Ongoing projects**: after initializing, ask the agent to organize existing experience ("整理已有经验"). It scans existing proposals, meeting notes, and in-project experience/convention documents, updates `cairn/ROADMAP.md`, and distills still-valid conclusions into topic notes while leaving original files untouched.
- - **Finished or uninitialized folders (one-shot graduation)**: no initialization or `cairn/` folder is needed. Open the folder and ask "See what experience in this folder can graduate" ("看看这个文件夹里,有哪些经验值得存进知识库"), or name a specific retrospective/summary note directly. The agent reads `~/.config/cairn/config.yaml`, excludes external reference material, proposes reusable candidates, and — once you confirm — writes the knowledge-base note (`type: project_insight`), updates `INDEX.md`, adds only `graduated_to` / `graduated_at` back-pointers to the source note, and logs a `经验入库:[[...]]` line under today's date if a project record note exists.
- - **Knowledge-base audit (`检查经验库`)**: run directly against an Obsidian knowledge-base folder without project init. List notes missing from `INDEX.md` and propose fixes for missing `type` / `summary` or a body not opening with **Background**. Register or edit only after confirmation or prior explicit authorization; manual notes without `graduated_from` remain valid.
- For a project audit, ask “检查项目经验” (check project experience). “检查知识文档”, “检查主题文档” and legacy “体检” requests are also recognized. A named file or document kind limits the scope; a general project request checks relevant topic notes, LOG and ROADMAP together. Findings and proposed repairs come first; checking alone does not authorize repairs or index writes. A normal project audit logs the check; an explicit read-only request forbids that write too.
- ## The two sides
- Project Cairn separates two lifecycles instead of putting every kind of information into one ever-growing file.
- | Side | What it keeps | Typical home | When it is read |
- |---|---|---|---|
- | **Project side** | Rules, progress, current conclusions, and local cases | root `AGENTS.md` and `cairn/` | while entering and advancing the project |
- | **Knowledge-base side** | Distilled knowledge that can be reused across projects | Obsidian, Notion, or Lark / Feishu wiki | when new work needs an earlier lesson |
- The project side keeps local facts and conclusions current. Once a lesson proves useful beyond that project, human-confirmed graduation distills it into the knowledge-base side. Each side remains authoritative for its own scope.
- ## How a lesson reaches the next project
- Take the messaging-bot problem:
- 1. Initialization writes the Cairn rules and configuration into the project.
- 2. As the agent investigates, meaningful progress is recorded in `LOG.md`.
- 3. Once the cause and fix are verified, the current conclusion moves into a topic note.
- 4. Stable conclusions from proposals, specs, plans, reviews, meeting notes, retrospectives, or in-project experience and convention notes (written by you or organized with AI) are also distilled into topic notes. Those process documents stay where they are and need no `type`.
- 5. The agent notices that the lesson may be reusable and proposes it as a graduation candidate.
- 6. After you approve, the agent removes project-specific noise, adds context and limits, records provenance, writes the note, and updates the provider's index.
- 7. A later project searches the knowledge base before solving the problem again. If a note shapes the work, `Cited.md` records a pointer rather than a duplicate.
- The interactive overview expands this journey into T0 through T8, including roadmap maintenance, audit, and re-graduation: [explore the full flow](https://iblinkq.github.io/project-cairn/).
- ## What it keeps
- Project Cairn does not stamp out a directory full of empty templates. Beyond the core initialization files, documents appear only when a real signal calls for them.
- | File | Responsibility |
- |---|---|
- | `AGENTS.md` | Rules and navigation |
- | `.cairn/config.yaml` | Machine-readable configuration |
- | `cairn/LOG.md` | Reverse-chronological history |
- | `cairn/ROADMAP.md` | Overall goal, plan, and current progress |
- | `cairn/<topic>.md` | Current truth for one topic |
- | `cairn/Reference/` | External source material owned by the project |
- | `cairn/Cited.md` | Pointers to knowledge that influenced the work |
- Schemas, configurations, and contracts consumed directly by code stay in the code tree. Cairn keeps the knowledge around them: why they look this way, what alternatives were tested, and what went wrong during implementation.
- Topic notes use Markdown and YAML frontmatter with at least a `type` field, following the minimal convention of Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing). Project Cairn does not claim to implement the complete OKF bundle. New project topics use `project_topic`; newly graduated notes use `project_insight`. Initialization does not ask for a type. Existing note types remain valid and are preserved unless a separate migration is confirmed. See [frontmatter](references/frontmatter.md).
- Graduated notes carry provenance through `graduated_from`, `contributors`, `graduated_by`, and `authoring_mode`, so readers can trace a conclusion back to the people, project, and source material that produced it.
- ## Automation boundaries
- - Project Cairn has no background hook and does not run after a chat ends.
- - Routine maintenance happens during normal work because the project's `AGENTS.md` carries the rules.
- - The agent may suggest a graduation candidate, but it cannot write to the long-term knowledge base without human confirmation.
- - Connecting Obsidian, Notion, or Lark / Feishu can be deferred until the first graduation.
- - Audit reports contradictions, stale conclusions, and omissions; it does not silently rewrite important decisions.
- Graduation writes from the project side to the knowledge-base side. Reuse works by searching first, then leaving a pointer in `Cited.md` when a note is actually used. It is explicit consumption, not background synchronization between two stores.
- ## Verified knowledge bases
- Project Cairn has verified graduation paths for:
- - **Obsidian**, using vault-relative files, `INDEX.md`, and native WikiLinks.
- - **Notion**, using a database as both the container and index, with structured metadata mapped to properties.
- - **Lark / Feishu wiki**, using nodes in a knowledge-space tree with links that can be read back.
- Every provider follows the behavioral contract in `references/provider-interface.md` while keeping its platform's native link and index model. Provider-specific execution paths live under `references/graduation/`. Before any write, the matching read-only preflight can check installation, authentication, and access:
- ```text
- scripts/obsidian-preflight.sh
- scripts/notion-preflight.sh
- scripts/lark-preflight.sh
- ```
- ## Learn more
- Project Cairn complements adjacent tools instead of replacing them:
- | Tool or approach | Main job | Relationship to Cairn |
- |---|---|---|
- | [LLM Wiki](https://github.com/karpathy) | Organize source material you have read into a wiki | LLM Wiki focuses on source knowledge; Cairn focuses on knowledge learned through project work |
- | [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) | Make knowledge files exchangeable by people and machines | OKF concerns format; Cairn concerns formation, maintenance, graduation, and reuse |
- | Agent memory | Preserve an agent's preferences and working context | Memory supports agent continuity; Cairn supports project-knowledge continuity |
- | [superpowers](https://github.com/obra/superpowers) | Make delivery more reliable through specs, plans, tests, and review | superpowers manages the process; Cairn keeps the stable conclusions learned from it |
- An agent remembering something is not the same as a project learning it.
- ## Docs map
- | Reference | Use it for |
- |---|---|
- | `references/init.md` | Initializing or retrofitting Project Cairn |
- | `references/maintenance.md` | Maintaining `LOG.md`, `ROADMAP.md`, and topic notes (including distilling process documents) |
- | `references/graduation.md` | Judging, distilling, and writing reusable knowledge (including one-shot graduation without init) |
- | `references/graduation/` | One execution path per provider (Lark wiki, Notion, Obsidian) |
- | `references/provider-interface.md` | The behavioral contract for provider adapters |
- | `references/consume.md` | Searching, using, and citing external knowledge |
- | `references/audit.md` | Finding project drift, contradictions, and missing records, plus standalone knowledge-base audits |
- | `references/upgrade.md` | Checking and upgrading an initialized project |
- | `references/frontmatter.md` | Fields for project notes and knowledge-base notes |
- | `references/branch-closure.md` | Salvaging knowledge before an exploration branch closes |
- | `references/zh-glossary.md` | Fixed terminology for Chinese project documentation |
- ## Contributing
- Issues and pull requests are welcome. Project Cairn is documentation-first, so most contributions belong in `SKILL.md`, `references/*.md`, `assets/templates/*`, or `scripts/`. If a change affects behavior, explain the reason and impact in the pull request.
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.