Skip to main content
skill CX Codex

Promote · wrg32786 — Claude Code skill: what it does, how to install

The Promote Claude Code skill turns useful conversation insights into lasting vault notes. It activates when a decision, fact, or idea should remain available after the session.

MIT ★ 26 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wrg32786/aigent-os --skill promote -a claude-code
Open on GitHub

What Promote does

Promote selects a meaningful part of a conversation and saves it as a vault artifact: a concept, person, or project note, or an entry in the decision log. Material spanning several categories becomes separate artifacts.

Each note captures the main insight, its reasoning, the context, and unresolved questions. By default, the skill considers the last 5–10 turns along with earlier exchanges explicitly referenced in the discussion. If the intended passage is unclear, it asks one focused question. A decision can also be added to vault/memory/DECISION_LOG.md.

What it helps with

  • save a conversation insight as a vault note
  • record a decision with its reasoning
  • create separate vault entries for a project, person, or concept

Example prompts for the agent

  • Save this conclusion in the vault with /promote.
  • Record our decision and the reasoning behind it.
  • Create a project note from this conversation.

How to install Promote

1Skills CLI (Vercel)

npx skills add wrg32786/aigent-os --skill promote -a claude-code

2Manually: put the files in place

~/.claude/skills/promote/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/promote/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about Promote

How do I install Promote in Claude Code?

Run npx skills add wrg32786/aigent-os --skill promote -a claude-code. The skill file is at ~/.claude/skills/promote/SKILL.md.

What does Promote do?

It selects lasting insights from a conversation and turns them into vault notes, such as a project or person entry or a decision-log item. Notes can include the reasoning and unresolved questions.

How is Promote different from saving a transcript?

It extracts durable insights rather than preserving the whole conversation. The daily note is handled by /close.

Source text

SKILL.md · MIT
---
name: Promote
description: "Promote conversation insights into durable vault notes, project updates, profiles, or doctrine. Use when saving an insight permanently or turning chat into a note."
---

# Promote

The conversation is a substrate. Most of what happens in it is ephemeral — task-specific, session-bound, useful in the moment and gone after. But some exchanges produce durable insights: a new architectural understanding, a person fact worth remembering, a doctrine pattern emerging, a decision that should be logged.

Without `/promote`, those insights live in the conversation transcript and decay. With `/promote`, the principal can elevate them to vault content the framework will surface in future sessions.

## When to use

- The conversation produced an insight that should outlive this session
- The principal said "we should remember that" or "make a note that…"
- A doctrine pattern is starting to emerge from the discussion
- A new person, project, or concept came up that needs a vault entry
- Use on prompts like: "/promote", "promote that", "make a note that", "save that insight", "elevate to doctrine", "capture this conversation", "remember that we decided", "this should be a vault note"

## How to execute

### Step 1 — Identify the slice to promote

Ask: which part of the conversation should become durable?

If the principal points to specific turns ("the last 10 messages about X"), use those. Otherwise:
- Default to the last 5-10 turns AND any explicitly-referenced earlier exchanges
- If unclear, ask one focused question: "Promote the {topic A} discussion or the {topic B} discussion?"

### Step 2 — Categorize the artifact

Map the slice to a vault category:

| If the slice is about... | Promote to... |
|---|---|
| A new concept, doctrine, or pattern | `vault/concepts/{slug}.md` |
| A person (collaborator, advisor, contact) | `vault/people/{name}.md` |
| A project (current or new) | `vault/projects/{slug}.md` |
| A decision with reasoning | append entry to `vault/memory/DECISION_LOG.md` |
| A learning sweep on a tool/framework | `vault/concepts/learning/{slug}.md` (use `/learn` instead) |
| A person/process rejection with reasoning | append entry to `vault/concepts/What I Am Not Building.md` |

If the slice is about multiple categories, produce multiple artifacts. Don't bundle.

### Step 3 — Extract the durable content

From the conversation slice, extract:
- **The insight or fact** (the load-bearing claim)
- **The reasoning that led to it** (why this is true / matters)
- **The context** (what triggered the conversation)
- **Open questions** (what's NOT yet resolved)

Drop:
- Conversational noise ("good point", "right", "that makes sense")
- Tool calls and intermediate exploration that doesn't matter to the conclusion
- Prior context that's already in other vault notes (link to those instead)

### Step 4 — Write the artifact

Use the appropriate vault note structure (frontmatter with title/tags/created/aliases, then content). Cross-link to existing notes that the slice references.

### Step 5 — Confirm and link

Output:

```
✅ Promoted to vault/{path}.md

Cross-references added:
- [[Existing Note 1]]
- [[Existing Note 2]]

Open questions captured:
- {question 1}
- {question 2}

Update [[MOC]] or [[MEMORY]] if this is high-signal? (y/n)
```

If the principal says yes, append a one-line entry to the appropriate MOC or to MEMORY.md.

### Step 6 — Optional: append to DECISION_LOG

If the promoted artifact reflects a decision (not just an insight), also append a one-line entry to `vault/memory/DECISION_LOG.md`:

```markdown
- 2026-04-27: {decision summary} → see [[promoted-artifact]]
```

This will trigger the decision-aging loop ([[Cost of Confidence]] sister doctrine) and surface 30/60/90-day check-ins via `/open`.

## What this skill is NOT

- **Not a transcript saver.** The daily note (`/close` artifact) handles that. `/promote` is for selective elevation.
- **Not a summarizer.** `/promote` extracts insights; it doesn't condense a long conversation. If the slice doesn't have a durable insight, don't promote — just let it stay in the transcript.
- **Not automatic.** The principal decides what graduates. Auto-promotion would dilute the vault.

## Anti-patterns this prevents

- Insights captured in chat transcripts that nobody reads later
- The principal saying "we already discussed this" but not knowing where
- Decisions made in conversation that don't make it to DECISION_LOG → lost reasoning
- Doctrine emerging in real-time but never crystallizing into a vault note → never applied

## Connects to

- `/close` — writes the daily note (transient outcome record)
- `/learn` — sister skill for tool/framework evaluations specifically
- `/decision-log` (forthcoming) — sister skill for decisions specifically
- [[Self-Improving CLAUDE.md]] — the broader pattern of converting conversation to durable rules
- [[Legibility Thesis]] — the meta-doctrine that demands ephemera become legible artifacts
- `vault/memory/MEMORY.md` — the index that gets updated when promoted artifacts are high-signal

© wrg32786 · MIT · wrg32786/aigent-os

Similar skills

All skills for Agent setup: memory, context, orchestration →

Promote by other authors comes first.

From the same set58

The whole set →
Sandbox Routing Sandbox Routing — a skill for Claude Code routes large-file analysis and lengthy command output through sandbox tools. It activates when an agent needs a small detail without pulling the full output into context. CX Codex +1 ★ 26repo stars resume Restores context for unfinished work. Run /resume to compare the saved capsule with live memory and take the next step. CX Codex +1 ★ 26repo stars research-deep The research-deep Claude Code skill combines vault notes, web sources, and GitHub research into a cited briefing with evidence and a recommendation. It runs on requests to investigate a topic or compare sources. CX Codex +1 ★ 26repo stars reconcile This Claude Code skill compares seven days of project attention with stated Tier-1 shares. Run it to reconcile attention or check for priority drift. CX Codex +1 ★ 26repo stars port-spec The port-spec Claude Code skill turns a complete written specification into code or a vault artifact. It activates for spec implementation, brief-based builds, and ports from specs. CX Codex +1 ★ 26repo stars pause The pause Claude Code skill saves a task’s state when work needs to stop temporarily. The next session offers a way to resume it. CX Codex +1 ★ 26repo stars orient The orient Claude Code skill points to the project map section relevant to a question about structure, ownership, rules, or next steps. It activates when someone asks where to look or how to proceed. CX Codex +1 ★ 26repo stars operator-setup The operator-setup Claude Code skill interviews a business operator and saves the answers for later sessions. It turns the stated goals and time-consuming work into three tailored next steps. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open