eandualem / eandualem/agent-backbone

Centralized tag-scoped skills store, materialized per agent at launch

Open
#213 12 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
5
Forks
1
Avg merge
38m
Merged PRs (30d)
89

Description

[from:leo] Design ask from Elias, 2026-09-10. Strategic owner: leo. Mechanism owner: this repo.

## Problem

Skills are duplicated per CLI and rot. Claude Code reads `.claude/skills/`, Codex reads `.agents/skills/`. On 2026-09-07 every `.claude/skills` in `~/ws` was hand-copied to `.agents/skills` (untracked); leo's copy was corrupted by a search-and-replace that turned a true historical statement into a false one. 27 retired skills sit inert in archives because there is no place to put a skill that more than one agent should have. Policies (#166) solved this for *short required rules*; skills — longer on-demand procedures — have no equivalent.

## Requirement

One centralized skills store. Skills grouped by tag. Backbone makes the right subset available to each agent at launch, in the directory its CLI actually reads, **without copying**. Hierarchy of tags via folder path:

```
/
/SKILL.md # everyone
coders// # agents tagged `coders`
coders/python// # agents tagged `coders` and `python`
career// # simon + desks
```

An agent tagged `coders python` receives the top level, `coders/`, and `coders/python/`. Same tag vocabulary as `backbone agent tag` / `templates use --tag` — one taxonomy for policies and skills.

Second-order requirement: a learning captured by one agent should be usable by another with the same tags. So agents need a sanctioned way to write a skill *into* the store under a tag, not only read from it.

## Constraints (from the config work this week — `orchestration/STANDARD.md`)

- **No copies.** A copy with no reader rots; we already have one corrupted instance. Materialize by symlink/junction from the store into the CLI's directory, or by whatever the CLI natively supports (Claude Code plugin marketplace with a local path? Codex `.agents/skills` symlink-following?). Verify per CLI **empirically** — behavioural marker, incurious probe — not from docs. Ask Feynman (`orchestration`) for the per-CLI loading table; he owns that method and the standard.
- **Referential integrity is mechanical.** The store is authored away from its readers, so the launch path must validate that every materialized skill resolves, the same way missing policies fail launch today.
- **Repo-local skills remain repo-owned.** A repo's own `.claude/skills` / `.agents/skills` content stays; backbone adds alongside, never overwrites, and removes only what it materialized.
- **Standalone.** Nothing in a repo should require backbone to function; if backbone is absent, the repo just has fewer skills.

## Research before design

1. What each CLI (Claude Code, Codex, Gemini, OpenCode, Cursor) reads, whether it follows symlinked skill dirs, and whether it has a native "skills path"/plugin mechanism that avoids materialization altogether.
2. How others solve cross-agent skill distribution — `npx skills` (vercel-labs/skills) copies, which is the failure mode we're avoiding; is there anything that shares by reference?
3. Downsides of folder-as-tag: skill wanting two unrelated tags (`python` and `career`) has no home in a tree. Is a flat store + tag metadata in SKILL.md frontmatter better than folders? Decide with evidence, not preference.

## Deliverable

A short design on this issue (store layout, tag model, materialization per CLI, write-back path, validation), then implement. Keep the CLI surface parallel to templates: `backbone skills list|preview AGENT|validate`, tags reused. Elias approves the design before implementation.

Contributor guide

Open the contributing guide

Research direction

Start with orchestration/STANDARD.md and the existing policy and template behavior referenced in the issue. Empirically probe Claude Code, Codex, Gemini, OpenCode, and Cursor for skill loading and symlink support, then compare folder tags with metadata and reference-based distribution. Done means Elias approves a short design covering layout, tags, materialization, write-back, validation, and the parallel skills CLI before implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
ai-infra-agents, cli, devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.