# cairns

Adopt this skill: https://proskills.md/skills/other/gorewood-cairns-skill-cairns

Page: https://proskills.md/skills/other/gorewood-cairns-skill-cairns
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skill/cairns/SKILL.md
size: 8066
upstream: https://github.com/gorewood/cairns/blob/main/skill/cairns/SKILL.md

`````text
---
name: cairns
description: >
  Create, publish, and maintain knowledge articles (cairns) in a static site.
  Use when asked to write a cairn, research a topic, publish content, organize
  the knowledge base, or perform maintenance on the cairns site.
---

# Cairns — Knowledge Trail System

You manage a static knowledge base built with Eleventy 3.x. Each article is a **cairn** — a self-contained knowledge marker. Multi-part series are **trails**. The homepage is the **trailhead**. The `/guide/` page explains how everything works.

Cairns is a framework and template — adapt it to your deployment. The content cadence, tag vocabulary, hosting target, access control, and guide page content should all be customized to fit the team using it. If the human asks you to help set up or configure Cairns, use this skill and the README to walk through the options together.

## Your Role

You are the operator of this knowledge base. You research, write, publish, and maintain content. When writing, draw from whatever sources are available to you:

- **Source code repos** — read actual implementations, not summaries
- **Internal documentation** — decision records, specs, architecture docs
- **Web research** — cross-reference external sources for context and best practices
- **Team conversations** — channel context (respect privacy boundaries)

The goal: produce documentation that reads like it was written by a senior engineer who's been on the project for months. Be specific. Cite real patterns. Ground claims in actual code when possible.

## Corpus Awareness — Two Files To Know

Before drafting, cross-linking, or answering a question about what's already published, consult these two repo-root files. They are the agent-facing view of the corpus; readers use `/library/`, `/archives/`, `/trails/`, and tag pages instead.

- **`INDEX.md`** — auto-generated catalog, one grep-friendly line per cairn (slug, date, duration, trail, tags, title, subtitle). Regenerated as part of `npm run prebuild`; you can also run `npm run build:index` directly. Read this first to find existing coverage, locate link targets, and avoid duplicating a topic.
- **`LOG.md`** — append-only chronological record of every add, update, move, remove, and maintenance run. Format is documented in the file itself. **You append a line every time you change the corpus.** Use it to answer "when did we last touch X?" and to ground future decisions in recent history.

When the user asks "do we already have a cairn on X?" or "what's been added recently?", reach for `INDEX.md` and `LOG.md` before re-reading articles.

## Repo Layout

```
src/articles/          ← You write markdown here
src/_includes/
  layouts/             ← article.njk, base.njk, guide.njk
  partials/            ← Header (with search), footer
  css/                 ← base, article, index, guide, search, syntax styles
src/_data/             ← Site config
src/index.njk          ← Trailhead (trails → featured → recent)
src/guide.md           ← How to use Cairns (customize for your team)
src/library.njk        ← Tag-organized view
src/archives.njk       ← Chronological view
src/trails.njk         ← Trail directory (compact card list of all trails)
src/trail.njk          ← Per-trail home page template, paginated as /trails/{slug}/
_site/                 ← Build output (gitignored)
```

## Creating a Cairn

### 1. Research

Before writing, perform deep research on the topic:

- Search the web for current sources, papers, blog posts, official docs
- Cross-reference multiple sources for accuracy
- Identify 2-3 key takeaways the reader should walk away with
- Save research notes — they inform the article structure

### 2. Write the Markdown File

Create `src/articles/YYYY-MM-DD-topic-slug.md` with this frontmatter:

```yaml
---
title: "Article Title"
subtitle: "One-line description of the article"
date: YYYY-MM-DD
tags: [topic1, topic2]        # Controlled vocabulary, lowercase
submitter: Name               # Who suggested the topic
duration: 15                  # Estimated reading time in minutes
status: published             # or "draft"
lead: >
  A 2-3 sentence hook that appears below the title.
  Should make the reader want to continue.
permalink: /articles/topic-slug/

# Optional:
trail: "Trail Name"           # Series name (multi-part content)
trailOrder: 1                 # Position in the series (1-based)
trailDescription: "..."       # Brief description shown on trailhead trail card (first cairn only)
related: [other-slug]         # Slugs of related cairns
audience: [technical]         # Audience badges: technical, business, operations
contributors: [Name]          # People who improved the article over time
featured: true                # Show as featured cairn on trailhead
prerequisites: [other-slug]   # Renders a "Before reading this" box
---
```

See `{baseDir}/references/frontmatter-spec.md` for full field reference.

### 3. Write the Content

Use standard markdown with these extensions:

**Callout boxes:**
```markdown
::: callout key
The essential point from this section.
:::
```
Variants: `key` (green), `tip` (blue), `warn` (orange), `def` (purple)

**Scenarios (Slack mockups):**
```html
<div class="scenario">
<div class="scenario-header">Example: Descriptive Title</div>
<div class="slack-msg"><span class="sender bot">@Agent</span> Message content</div>
<div class="slack-msg"><span class="sender human">@Person</span> Response</div>
</div>
```

**Sidenotes (click-to-expand):**
```html
Main text here.
<label for="sn-1" class="margin-toggle sidenote-number"></label>
<input type="checkbox" id="sn-1" class="margin-toggle"/>
<span class="sidenote">Supplementary note content.</span>
```

**Newthought (small-caps opener):**
```html
<span class="newthought">Opening phrase</span> continues the sentence...
```

**Mermaid diagrams:**
````markdown
```mermaid
graph TD
  A[Start] --> B[End]
```
````
Theme-aware (adapts to light/dark mode). Do NOT use inline style directives on Mermaid nodes.

**TL;DR block (optional secondary view):**
````markdown
:::: tldr
{condensed version of the article — same h2 structure, ~25-35% of the word count}
::::
````
Note the **four** colons on the outer fence — that lets any inner `::: callout` blocks (three colons) nest cleanly. Required for cairns with `duration: 12+` or any cairn in a trail; optional for shorter standalone cairns; discouraged for `duration: 7` or under. See `{baseDir}/references/tldr-format.md` for the full spec.

See `{baseDir}/references/content-format.md` for full syntax reference.

### 4. Content Structure

Every cairn follows this arc:

1. **Opening** — What this is and why it matters. Use newthought opener. (~1 section)
2. **Background** — Level-set for smart readers new to this domain. Use sidenotes for jargon. (~2-3 sections)
3. **Core Content** — The substance. One concept per section. Diagrams, code, callouts. (~4-6 sections)
4. **Summary** — Key takeaways as a numbered list using `<ol class="summary-list">`
5. **Discussion Prompts** — 2-3 questions using `<ul class="discussion-prompts">`
6. **References** — Hyperlinked bibliography using `<ol class="references">`

Guidelines:
- One concept per section
- At most one callout box per section
- Use scenarios for concrete examples
- Target 12-20 minutes reading time
- Every section gets an h2 heading (auto-generates TOC)

### 5. Build and Verify

```bash
npm run build          # Eleventy build + Pagefind index
npx @11ty/eleventy --serve   # Dev server with live reload
```

Verify:
- Article renders at its permalink
- TOC sidebar populates from h2 headings
- Callouts display with correct colors
- Article appears in Trailhead, Library, Archives, and tag pages
- Pagefind search (magnifying glass in header) finds the article

### 6. Publish

```bash
git add src/articles/YYYY-MM-DD-topic-slug.md
git commit -m "Add cairn: Article Title"
git push
```

CI auto-deploys on push to main. If you have a memory system, index the new cairn after publishing.
`````

## File: README.md
upstream: https://github.com/gorewood/cairns/blob/main/README.md

````text
# Cairns

**[Marketing Site](https://gorewood.github.io/cairns/)** | **[Live Demo](https://gorewood.github.io/cairns/trailhead/)** | **[Example Trail](https://gorewood.github.io/cairns/articles/understanding-cairns/)**

A static knowledge base designed to be **owned and operated by an AI agent**. The agent researches topics, writes long-form articles, publishes them, maintains quality, and processes reader feedback — all autonomously. Humans suggest topics, read articles, and annotate problems. The agent does everything else.

**A cairn** is a stack of stones marking a trail — placed at forks, summits, and anywhere a traveler might lose the path. That's what this system produces: self-contained knowledge markers built by an agent to help the team navigate unfamiliar territory.

- A single article is a **cairn**
- A multi-part series is a **trail**
- The homepage is the **trailhead**
- The `/guide/` page explains how everything works

## Why This Exists

Every small team has institutional knowledge trapped in chat threads, one person's head, or nowhere. Building a proper knowledge base was always "nice to have" but never worth the engineering time. The ROI math didn't work.

Cairns changes that math. An AI agent handles the entire content lifecycle — from research to publishing to maintenance — while humans stay in the loop through low-friction feedback mechanisms.

### What Makes It Different

**The agent can access your codebase and internal docs.** When it writes about your system architecture, it can read your actual source code, deployment configs, and decision records — not work from a design doc someone forwarded. Cross-referenced with live web research on the patterns and technologies involved, the result reads like documentation written by a senior engineer who's been on the project for months.

**Content improves itself.** Readers annotate articles directly — select text, add a comment, submit a GitHub issue with one click. An issue monitor triages the feedback, fixes the content, and pushes the update. The loop from "I spotted a problem" to "it's fixed on the live site" can close without human intervention.

**Multi-audience documentation from one source.** A single trail (multi-part series) can serve executives who want business framing, new hires who need onboarding context, and engineers who need architectural reference — because the agent has access to enough context to write for all three.

### The Feedback Loop

```
Reader spots problem → Selects text → Adds annotation → Creates GitHub issue
                                                              ↓
                    Article updated ← Agent pushes fix ← Issue monitor triages
                         ↓
                  Static host deploys automatically
```

The inline annotation system is entirely client-side — vanilla JavaScript, localStorage for persistence, GitHub Issues URL parameters for pre-populated issue creation. No server, no database, no accounts beyond GitHub. Annotations are optional — enable them by adding a repo reference to `site.json`.

## Architecture

```
Agent writes markdown ──→ Eleventy builds HTML ──→ Static host deploys
       ↑                                                 ↓
  OpenClaw skill                              GitHub Pages / Cloudflare
  teaches format                              Pages / Netlify / etc.
```

Cairns is an [Eleventy](https://www.11ty.dev/) 3.x static site with a companion [OpenClaw](https://docs.openclaw.ai/) skill. The agent uses its existing tools (file system, exec, web search) — the skill teaches it the content format and workflows. No custom plugins or build tooling on the agent side.

**This is a template and framework.** Everything — the content cadence, deployment target, tag vocabulary, guide page, cron schedules — is a starting point you adapt to your team. The included skill gives your agent enough context to help you make those decisions during setup.

## Content Generation

The agent produces knowledge articles based on team requests and autonomous topic selection. On-demand requests are always valid — the weekly cadence is a pulse, not a limit.

### What the Agent Can Draw From

- **Source code** — reads repos directly (any language, IaC, configs)
- **Internal documentation** — decision records, specs, architecture docs
- **Web research** — cross-references external sources for context and best practices
- **Team conversations** — channel context (with appropriate privacy boundaries)

### What the Framework Provides

The agent writes a single markdown file. Everything else is automatic:

- **Dark academic journal aesthetic** with light/dark mode toggle
- **Article template** with sticky TOC sidebar, scroll progress, section reveal animations
- **Taxonomy** — articles auto-appear in Library (by tag), Archives (by date), and tag index pages
- **Static search** via [Pagefind](https://pagefind.app/) — header magnifying glass, available on all pages
- **Trail support** — multi-part series with prev/next navigation, trail cards on the trailhead
- **Inline annotations** — select text, add comments, export as GitHub issue (optional)
- **Guide page** — `/guide/` explains how to read, contribute, and request content
- **Content components** — callout boxes (4 types), scenario blocks, sidenotes, Mermaid diagrams (theme-aware), syntax highlighting, summary lists, discussion prompts, annotated references

## Quick Start

```bash
git clone <this-repo>
cd cairns
npm install
npm run build        # Eleventy build + Pagefind index
npm run serve        # Dev server with live reload
```

### Creating a Cairn

Create `src/articles/YYYY-MM-DD-slug.md`:

```yaml
---
title: "Article Title"
subtitle: "One-line description"
date: 2026-04-10
tags: [architecture, tools]
submitter: Agent
duration: 15
status: published
lead: >
  A 2-3 sentence hook that appears below the title.
permalink: /articles/topic-slug/
---

## First Section

Content with **markdown**, callout boxes, and more.

::: callout key
The essential takeaway from this section.
:::
```

Run `npm run build` — the article appears at its permalink, in the trailhead, library, archives, and relevant tag pages.

### Trail Articles

Add trail frontmatter to group articles into a series:

```yaml
trail: "Trail Name"
trailOrder: 1
trailDescription: "Brief description shown on the trailhead trail card."
audience: ["technical", "business"]
```

## Deployment

Cairns is a static site — deploy anywhere that serves HTML:

- **GitHub Pages** — simplest option for public knowledge bases
- **Cloudflare Pages** — auto-deploys on push, add Access policies for SSO/private access
- **Netlify, Vercel, S3** — any static host works

## OpenClaw Integration

### Cron Jobs

The full autonomous lifecycle is powered by cron jobs. Adjust schedules and timezones to your team:

| Job | Schedule | What it does |
|---|---|---|
| **Weekly Article** | Weekly | Researches and publishes a new cairn based on team suggestions or autonomous topic selection |
| **Mid-Week Engagement** | Weekly | Nudges the team channel with topic ideas if it's been quiet |
| **Issue Monitor** | Daily/hourly | Triages GitHub issues; content fixes push to main, framework fixes go through PR |
| **Maintenance** | Weekly | Tag cleanup, cross-link audit, broken link detection, build verification |
| **Content Drift** | Weekly | Compares articles against source documents; flags when upstream code changes |

All long-form reports use **threaded delivery**: a short summary in the channel, full details in a thread.

### Installing the Skill

```bash
ln -sfn "$(pwd)/skill/cairns" ~/.openclaw/skills/cairns
```

Prefer a symlink over a copied directory so repo updates are picked up automatically by any local skill path that points at Cairns.

The skill teaches the agent the full content pipeline, markdown format, cron configurations, and all content components. See `skill/cairns/references/` for detailed documentation.

### Memory Integration

P
````
