/beacon-memory-promote

name: beacon-memory-promote
description: Install approved Beacon project memory as an Agent Skill in the repository (.agents/skills/<slug>/SKILL.md), so every skill-capable harness loads the lesson automatically without a memory lookup. Use when the user asks to "make this a skill", "promote", "install", or "share" an approved Beacon memory, or wants the team's agents to always follow a learned workflow or convention.
license: MIT
compatibility: Requires the Beacon CLI (beacon) on PATH. Local only. Writes files inside the current project.
metadata:
  author: asymptote-labs
  homepage: https://docs.beacon.sh/cli/memory
  version: "0.1.0"

Beacon memory promote: memory to skill

Approved memory is recalled on demand. A **skill** is loaded by the harness itself whenever its description matches the task, and when it is committed to the repository it reaches every teammate and every harness that reads `.agents/skills` (Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Amp, goose, and others; Claude Code reads `.claude/skills`).

Promote only what earns that. Each installed skill adds to what every agent considers on every task.

What to promote

Good candidates:

• `workflow` and `convention` memories that apply to many tasks in this repository.
• A `debugging_pattern` for a failure that keeps recurring.

Leave in memory, where recall finds them when needed:

• One-off gotchas tied to a single file or incident.
• Anything that duplicates the repository's CLAUDE.md, AGENTS.md, or contributing docs.

Suggest editing those docs instead.

Step 1: choose the memory

beacon memory list --limit 25
beacon memory show <memory-id> --json

The skill commands take the **candidate** ID, which is the `candidate_id` field of the memory.

Step 2: preview

beacon memory skills preview <candidate-id>

Check the preview with the user:

• The `description` is the title plus the memory's applicability. It decides when a

harness loads the skill, so it must name the trigger (a command, path, or error). If it is vague, the fix is a better memory: draft a sharper title and applicability, approve a replacement through the `beacon-memory-distill` workflow, and supersede the old one.

• The body must hold no secrets, hostnames, or personal details. It is about to become a

file that is likely to be committed.

Step 3: install, after the user confirms

beacon memory skills install <candidate-id>

This writes `.agents/skills/<slug>/SKILL.md` in the project (or the `--project` path). It refuses to overwrite an existing file; pass `--force` only when the user wants to replace the generated skill, and never over a file a person has edited by hand without asking.

For Claude Code, which reads `.claude/skills` rather than `.agents/skills`, offer to link the skill there:

mkdir -p .claude/skills && ln -s ../../.agents/skills/<slug> .claude/skills/<slug>

Step 4: hand off

Show the path and remind the user that:

• The file carries Beacon provenance under `metadata` (`beacon_memory_id`,

`beacon_candidate_id`), so a reviewer can trace it back to the approved memory and the source session.

• It becomes team-wide only when they commit it. Do not commit or push unless they ask.
• If the memory is later superseded, the installed skill is not updated automatically.

Re-run preview and install with `--force` from the replacement candidate.

Boundaries

• Never install without the user seeing the preview and confirming.
• Never approve or edit memory here. Use `beacon-memory-distill`.
• Do not write to user-level skill directories (such as `~/.agents/skills`). Beacon memory

is scoped to a project.