⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.1.0

cairns

gorewood@gorewood⭐ 1 stars· last commit 7d ago· 0 open issues

>

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 1 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Cairns

Marketing Site | Live Demo | Example Trail

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 3.x static site with a companion OpenClaw 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 — 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

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:

---
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:

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:

JobScheduleWhat it does
Weekly ArticleWeeklyResearches and publishes a new cairn based on team suggestions or autonomous topic selection
Mid-Week EngagementWeeklyNudges the team channel with topic ideas if it's been quiet
Issue MonitorDaily/hourlyTriages GitHub issues; content fixes push to main, framework fixes go through PR
MaintenanceWeeklyTag cleanup, cross-link audit, broken link detection, build verification
Content DriftWeeklyCompares 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

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

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skill/cairns/SKILL.md7.9 KBupstream ↗
    ---
    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.
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/gorewood-cairns-skill-cairns.md

// REPO STATS

1 stars
0 open issues
Last commit: 7d ago