--- name: beacon-memory-promote description: Install approved Beacon project memory as an Agent Skill in the repository (.agents/skills//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 for local memory, or a Beacon Cloud MCP connection (beacon-managed) for memory approved there. 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. ## Memory approved through Beacon Cloud Memory approved through Beacon Cloud MCP is promoted with `beacon_memory_skill`, which returns the same `SKILL.md` that `beacon memory skills install` writes, plus the path to write it at. Beacon Cloud cannot write into the repository, so you write the file: 1. Find the memory with `beacon_memory_search` and read it with `beacon_memory_get`. 2. Call `beacon_memory_skill` with its `memory_id`, and check the returned `content` with the user as in Step 2. 3. After the user confirms, write `content` to the returned `path` (`.agents/skills//SKILL.md`) in the repository. If a file is already there, show the difference and ask before replacing it. For Claude Code, offer the same link as in Step 3. 4. Hand off as in Step 4. For local memory, follow the steps below. ## Step 1: choose the memory ```bash beacon memory list --limit 25 beacon memory show --json ``` The skill commands take the **candidate** ID, which is the `candidate_id` field of the memory. ## Step 2: preview ```bash beacon memory skills preview ``` 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 ```bash beacon memory skills install ``` This writes `.agents/skills//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: ```bash mkdir -p .claude/skills && ln -s ../../.agents/skills/ .claude/skills/ ``` ## 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, locally or through Beacon Cloud. Use `beacon-memory-distill`. - Do not write to user-level skill directories (such as `~/.agents/skills`). Beacon memory is scoped to a project.