asymptote-labs/agent-beacon/beacon-memory-promote

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.

1. After the user confirms, write content to the returned path

(.agents/skills/<slug>/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.

1. Hand off as in Step 4.

For local memory, follow the steps below.

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, 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.