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
npx skills add wrg32786/aigent-os --skill promote -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/promote/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/promote/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill promote -a codex2Manually: put the files in place
.agents/skills/promote/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill promote -a cursor2Manually: put the files in place
.cursor/skills/promote/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/promote2Manually: put the files in place
.github/skills/promote/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill promote -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/promoteManually: put the files in place
.devin/skills/promote/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill promote -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.