Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Render memory skills from pkg/asymptoteobserve

Claude74178edc3d6b
diff --git a/cli/beacon/internal/learning/skills.go b/cli/beacon/internal/learning/skills.go
index 1ccbe8cb..90454fb0 100644
--- a/cli/beacon/internal/learning/skills.go
+++ b/cli/beacon/internal/learning/skills.go
@@ -5,7 +5,6 @@ import (
"os"
"path/filepath"
"strings"
- "unicode"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
@@ -38,43 +37,10 @@ func CandidateMemoryForSkill(store *Store, candidateID string) (asymptoteobserve
return candidate, memory, nil
}
+// RenderSkill renders an approved memory as a SKILL.md. The renderer lives in
+// pkg/asymptoteobserve so Beacon Cloud MCP produces the same file.
func RenderSkill(candidate asymptoteobserve.LearningCandidateV1, memory asymptoteobserve.LearningMemoryV1) string {
- slug := SkillSlug(memory)
- var b strings.Builder
- // Provenance lives under metadata, the Agent Skills spec's string map for
- // client-specific keys, so a generated skill validates and can be published
- // like any other.
- b.WriteString("---\n")
- b.WriteString("name: " + slug + "\n")
- b.WriteString("description: " + yamlQuote(skillDescription(memory)) + "\n")
- b.WriteString("metadata:\n")
- b.WriteString(" beacon_memory_id: " + yamlQuote(memory.ID) + "\n")
- b.WriteString(" beacon_candidate_id: " + yamlQuote(candidate.ID) + "\n")
- if memory.Kind != "" {
- b.WriteString(" beacon_memory_kind: " + yamlQuote(memory.Kind) + "\n")
- }
- if len(memory.Tags) > 0 {
- b.WriteString(" beacon_tags: " + yamlQuote(strings.Join(memory.Tags, ", ")) + "\n")
- }
- b.WriteString("---\n\n")
- b.WriteString("# " + memory.Title + "\n\n")
- if memory.Applicability != "" {
- b.WriteString("Use this skill " + ensureTrailingPeriod(memory.Applicability) + "\n\n")
- }
- b.WriteString("## Guidance\n\n")
- b.WriteString(strings.TrimSpace(memory.Body))
- b.WriteString("\n\n")
- if len(memory.Evidence) > 0 {
- b.WriteString("## Beacon Evidence\n\n")
- for _, evidence := range memory.Evidence {
- b.WriteString("- Trace `" + evidence.TraceID + "`")
- if evidence.Summary != "" {
- b.WriteString(": " + evidence.Summary)
- }
- b.WriteString("\n")
- }
- }
- return b.String()
+ return asymptoteobserve.RenderLearningSkill(candidate, memory)
}
func InstallSkill(projectPath string, candidate asymptoteobserve.LearningCandidateV1, memory asymptoteobserve.LearningMemoryV1, force bool) (SkillInstallResult, error) {
@@ -85,7 +51,7 @@ func InstallSkill(projectPath string, candidate asymptoteobserve.LearningCandida
return SkillInstallResult{}, fmt.Errorf("project path is required to install a skill")
}
slug := SkillSlug(memory)
- path := filepath.Join(projectPath, ".agents", "skills", slug, "SKILL.md")
+ path := filepath.Join(projectPath, filepath.FromSlash(asymptoteobserve.LearningSkillPath(slug)))
if !force {
if _, err := os.Stat(path); err == nil {
return SkillInstallResult{}, fmt.Errorf("skill already exists: %s (use --force to overwrite)", path)
@@ -104,81 +70,5 @@ func InstallSkill(projectPath string, candidate asymptoteobserve.LearningCandida
}
func SkillSlug(memory asymptoteobserve.LearningMemoryV1) string {
- base := strings.TrimSpace(memory.Title)
- if base == "" {
- base = memory.ID
- }
- var out strings.Builder
- lastDash := false
-runes:
- for _, r := range strings.ToLower(base) {
- switch {
- case unicode.IsLetter(r) || unicode.IsDigit(r):
- out.WriteRune(r)
- lastDash = false
- case !lastDash:
- out.WriteByte('-')
- lastDash = true
- }
- // Stop at 48 bytes so the name, with the beacon- prefix, stays within the
- // Agent Skills limit of 64 characters.
- if out.Len() >= 48 {
- break runes
- }
- }
- slug := strings.Trim(out.String(), "-")
- if slug == "" {
- slug = "beacon-memory"
- }
- if !strings.HasPrefix(slug, "beacon-") {
- slug = "beacon-" + slug
- }
- return slug
-}
-
-// maxSkillDescription is the Agent Skills limit on the description field.
-const maxSkillDescription = 1024
-
-// skillDescription is what a harness reads to decide when to load the skill, so
-// it names the situation as well as the lesson: the title's first sentence, then
-// the memory's applicability as a "Use ..." clause.
-func skillDescription(memory asymptoteobserve.LearningMemoryV1) string {
- description := ensureTrailingPeriod(firstSentence(memory.Title))
- if applies := strings.Join(strings.Fields(memory.Applicability), " "); applies != "" {
- description += " Use " + ensureTrailingPeriod(applies)
- }
- if runes := []rune(description); len(runes) > maxSkillDescription {
- description = strings.TrimSpace(string(runes[:maxSkillDescription-1])) + "…"
- }
- return description
-}
-
-func yamlQuote(value string) string {
- escaped := strings.ReplaceAll(value, `\`, `\\`)
- escaped = strings.ReplaceAll(escaped, `"`, `\"`)
- return `"` + escaped + `"`
-}
-
-func firstSentence(value string) string {
- value = strings.TrimSpace(value)
- if value == "" {
- return "Beacon approved project memory."
- }
- for _, sep := range []string{".", "\n"} {
- if idx := strings.Index(value, sep); idx > 0 {
- return strings.TrimSpace(value[:idx])
- }
- }
- return value
-}
-
-func ensureTrailingPeriod(value string) string {
- value = strings.TrimSpace(value)
- if value == "" {
- return ""
- }
- if strings.HasSuffix(value, ".") {
- return value
- }
- return value + "."
+ return asymptoteobserve.LearningSkillSlug(memory)
}
diff --git a/pkg/asymptoteobserve/learning_skill.go b/pkg/asymptoteobserve/learning_skill.go
new file mode 100644
index 00000000..a2bcf25e
--- /dev/null
+++ b/pkg/asymptoteobserve/learning_skill.go
@@ -0,0 +1,137 @@
+package asymptoteobserve
+
+import (
+ "strings"
+ "unicode"
+)
+
+// LearningSkillPath is where a rendered memory skill goes, relative to the
+// project root: the cross-harness .agents/skills directory most skill-capable
+// runtimes read (Claude Code reads .claude/skills instead).
+func LearningSkillPath(slug string) string {
+ return ".agents/skills/" + slug + "/SKILL.md"
+}
+
+// RenderLearningSkill renders an approved memory as an Agent Skills SKILL.md.
+// The CLI's `beacon memory skills` and the hosted Beacon Cloud MCP both call it,
+// so a skill promoted from either is byte-for-byte the same file.
+func RenderLearningSkill(candidate LearningCandidateV1, memory LearningMemoryV1) string {
+ slug := LearningSkillSlug(memory)
+ var b strings.Builder
+ // Provenance lives under metadata, the Agent Skills spec's string map for
+ // client-specific keys, so a generated skill validates and can be published
+ // like any other.
+ b.WriteString("---\n")
+ b.WriteString("name: " + slug + "\n")
+ b.WriteString("description: " + skillYAMLQuote(learningSkillDescription(memory)) + "\n")
+ b.WriteString("metadata:\n")
+ b.WriteString(" beacon_memory_id: " + skillYAMLQuote(memory.ID) + "\n")
+ b.WriteString(" beacon_candidate_id: " + skillYAMLQuote(candidate.ID) + "\n")
+ if memory.Kind != "" {
+ b.WriteString(" beacon_memory_kind: " + skillYAMLQuote(memory.Kind) + "\n")
+ }
+ if len(memory.Tags) > 0 {
+ b.WriteString(" beacon_tags: " + skillYAMLQuote(strings.Join(memory.Tags, ", ")) + "\n")
+ }
+ b.WriteString("---\n\n")
+ b.WriteString("# " + memory.Title + "\n\n")
+ if memory.Applicability != "" {
+ b.WriteString("Use this skill " + skillTrailingPeriod(memory.Applicability) + "\n\n")
+ }
+ b.WriteString("## Guidance\n\n")
+ b.WriteString(strings.TrimSpace(memory.Body))
+ b.WriteString("\n\n")
+ if len(memory.Evidence) > 0 {
+ b.WriteString("## Beacon Evidence\n\n")
+ for _, evidence := range memory.Evidence {
+ b.WriteString("- Trace `" + evidence.TraceID + "`")
+ if evidence.Summary != "" {
+ b.WriteString(": " + evidence.Summary)
+ }
+ b.WriteString("\n")
+ }
+ }
+ return b.String()
+}
+
+// LearningSkillSlug is the skill's name and directory: the memory title in
+// lowercase words joined by dashes, prefixed with beacon-.
+func LearningSkillSlug(memory LearningMemoryV1) string {
+ base := strings.TrimSpace(memory.Title)
+ if base == "" {
+ base = memory.ID
+ }
+ var out strings.Builder
+ lastDash := false
+runes:
+ for _, r := range strings.ToLower(base) {
+ switch {
+ case unicode.IsLetter(r) || unicode.IsDigit(r):
+ out.WriteRune(r)
+ lastDash = false
+ case !lastDash:
+ out.WriteByte('-')
+ lastDash = true
+ }
+ // Stop at 48 bytes so the name, with the beacon- prefix, stays within the
+ // Agent Skills limit of 64 characters.
+ if out.Len() >= 48 {
+ break runes
+ }
+ }
+ slug := strings.Trim(out.String(), "-")
+ if slug == "" {
+ slug = "beacon-memory"
+ }
+ if !strings.HasPrefix(slug, "beacon-") {
+ slug = "beacon-" + slug
+ }
+ return slug
+}
+
+// maxLearningSkillDescription is the Agent Skills limit on the description field.
+const maxLearningSkillDescription = 1024
+
+// learningSkillDescription is what a harness reads to decide when to load the
+// skill, so it names the situation as well as the lesson: the title's first
+// sentence, then the memory's applicability as a "Use ..." clause.
+func learningSkillDescription(memory LearningMemoryV1) string {
+ description := skillTrailingPeriod(skillFirstSentence(memory.Title))
+ if applies := strings.Join(strings.Fields(memory.Applicability), " "); applies != "" {
+ description += " Use " + skillTrailingPeriod(applies)
+ }
+ if runes := []rune(description); len(runes) > maxLearningSkillDescription {
+ description = strings.TrimSpace(string(runes[:maxLearningSkillDescription-1])) + "…"
+ }
+ return description
+}
+
+func skillYAMLQuote(value string) string {
+ escaped := strings.ReplaceAll(value, `\`, `\\`)
+ escaped = strings.ReplaceAll(escaped, `"`, `\"`)
+ return `"` + escaped + `"`
+}
+
+func skillFirstSentence(value string) string {
+ value = strings.TrimSpace(value)
+ if value == "" {
+ return "Beacon approved project memory."
+ }
+ for _, sep := range []string{".", "\n"} {
+ if idx := strings.Index(value, sep); idx > 0 {
+ return strings.TrimSpace(value[:idx])
+ }
+ }
+ return value
+}
+
+func skillTrailingPeriod(value string) string {
+ value = strings.TrimSpace(value)
+ if value == "" {
+ return ""
+ }
+ if strings.HasSuffix(value, ".") {
+ return value
+ }
+ return value + "."
+}
diff --git a/pkg/asymptoteobserve/learning_skill_test.go b/pkg/asymptoteobserve/learning_skill_test.go
new file mode 100644
index 00000000..630bd553
--- /dev/null
+++ b/pkg/asymptoteobserve/learning_skill_test.go
@@ -0,0 +1,76 @@
+package asymptoteobserve
+
+import (
+ "strings"
+ "testing"
+)
+
+// The CLI and Beacon Cloud MCP both render promoted memory with
+// RenderLearningSkill, and a skill a team committed from one must not churn when
+// re-rendered by the other, so the exact output is pinned here.
+func TestRenderLearningSkillGolden(t *testing.T) {
+ evidence := []LearningEvidenceV1{{TraceID: "trace-1", Summary: "Retry fixed a transient package smoke failure"}, {TraceID: "trace-2"}}
+ candidate := LearningCandidateV1{ID: "candidate-1", Evidence: evidence}
+ memory := LearningMemoryV1{
+ ID: "memory-1",
+ CandidateID: candidate.ID,
+ Kind: LearningMemoryKindDebuggingPattern,
+ Title: `Retry "package smoke" once. Then debug`,
+ Body: "\nInspect the error and rerun once before changing code.\n\n",
+ Applicability: "when package smoke fails\nwith a transient network error",
+ Tags: []string{"beacon", "debugging_pattern"},
+ Evidence: evidence,
+ }
+ want := `---
+name: beacon-retry-package-smoke-once-then-debug
+description: "Retry \"package smoke\" once. Use when package smoke fails with a transient network error."
+metadata:
+ beacon_memory_id: "memory-1"
+ beacon_candidate_id: "candidate-1"
+ beacon_memory_kind: "debugging_pattern"
+ beacon_tags: "beacon, debugging_pattern"
+---
+
+# Retry "package smoke" once. Then debug
+
+Use this skill when package smoke fails
+with a transient network error.
+
+## Guidance
+
+Inspect the error and rerun once before changing code.
+
+## Beacon Evidence
+
+- Trace ` + "`trace-1`" + `: Retry fixed a transient package smoke failure
+- Trace ` + "`trace-2`" + `
+`
+ if got := RenderLearningSkill(candidate, memory); got != want {
+ t.Fatalf("rendered skill changed:\n%s\nwant:\n%s", got, want)
+ }
+ if got := LearningSkillPath(LearningSkillSlug(memory)); got != ".agents/skills/beacon-retry-package-smoke-once-then-debug/SKILL.md" {
+ t.Fatalf("path = %s", got)
+ }
+}
+
+func TestLearningSkillSlugBounds(t *testing.T) {
+ for title, want := range map[string]string{
+ "": "beacon-memory-7",
+ "!!!": "beacon-memory",
+ "Beacon: hooks first": "beacon-hooks-first",
+ "Ünïcode títle": "beacon-ünïcode-títle",
+ strings.Repeat("ab ", 40): "beacon-" + strings.TrimSuffix(strings.Repeat("ab-", 16), "-"),
+ } {
+ got := LearningSkillSlug(LearningMemoryV1{ID: "memory-7", Title: title})
+ if got != want {
+ t.Errorf("slug(%q) = %q, want %q", title, got, want)
+ }
+ if len(got) > 64 {
+ t.Errorf("slug(%q) is %d bytes, over the Agent Skills limit", title, len(got))
+ }
+ }
+ long := LearningMemoryV1{Title: "t", Applicability: strings.Repeat("x", 2000)}
+ if got := learningSkillDescription(long); len([]rune(got)) != maxLearningSkillDescription {
+ t.Fatalf("description is %d runes, want the %d cap", len([]rune(got)), maxLearningSkillDescription)
+ }
+}