Production code no longer reads or writes .skillshare-meta.json sidecars:
- InstallAgentFromDiscovery: write to centralized store via WriteMetaToStore
- agent_check.go: read from centralized store passed as parameter
- handler_skills.go: read agents from s.agentsStore
- audit.go: readMetaFileHashes reads from parent .metadata.json
- analyzer_metadata.go: extract findMetaEntry to deduplicate walk logic
- uninstall_agents.go: remove entry from centralized store on uninstall
- batchUpdateAgents: pass store to reinstallAgent, remove dead field
- Replace LoadMetadata+nil guard with LoadMetadataOrNew across 6 files
- Remove MetadataEntry.Name (json:"-", never set in production) and
FullName() method (only used in one test)
- Add LoadMetadataOrNew() helper to replace 8+ instances of the
LoadMetadata + nil guard boilerplate
Extract the identical walk-and-reconcile logic from ReconcileGlobalSkills
and ReconcileProjectSkills into reconcileSkillsWalk() in a new
reconcile_core.go file. Both callers are now thin wrappers.
- Move git helpers (isGitRepo, gitCurrentBranch, gitRemoteOrigin) to core
- Add pruneStaleEntries() shared helper
- Project version injects gitignore collection via onFound callback
- ~140 lines of duplication eliminated
Grouped install tests now assert full-path keys (e.g. 'frontend/pdf-skill')
instead of basename keys, and verify that legacy basename keys are removed
after migration.
reinstallAgent previously called install.Install() which expects
directory-based skill installation. Agent sources point to .md files,
so the subdir resolver rejected them.
Now uses DiscoverFromGit/DiscoverFromGitSubdir + InstallAgentFromDiscovery
which correctly handles single-file agent copies. Also preserves the
original repo subdir scope for monorepo installs and reconstructs the
correct destination subdirectory for grouped agents.
All call sites that looked up metadata entries using filepath.Base()
now use store.GetByPath(relPath) which handles both full-path keys
and legacy basename+group keys transparently.
Also fixes makeInstallOpts() to set SourceDir from updateContext,
preventing nested skill updates from writing metadata to wrong dir.
Metadata store entries for grouped skills (e.g. frontend/foo, backend/foo)
were keyed by basename only, causing the second install to overwrite the
first. This changes the key to the full relative path.
Key changes:
- WriteMetaToStore: use full rel path as key, clean up legacy basename key
- Add KeyToRelPath() helper and MigrateLegacyKey() method for backward compat
- Reconcile: migrate legacy basename keys to full-path keys on load
- install_queries: guard against double-prefixing with KeyToRelPath
- LoadMetadata: auto-run sidecar cleanup on every load (idempotent)
- migrateAgentSidecars: recurse into subdirectories
- mergeSkillSidecar: use full-path keys, detect tracked repos
Code quality fixes from review:
- Extract RemoveByNames() to eliminate copy-paste in uninstall Phase 7
- Add MetadataKindSkill/MetadataKindAgent constants
- Remove dual-write shim (findSkillsRoot + writeMetaToCentralized)
- install_apply.go uses WriteMetaToStore with SourceDir (no sidecar)
- Move LoadMetadata out of walk loops (P0 efficiency fix)
- isGroupDir accepts store parameter to avoid redundant loads
- Add SourceDir to InstallOptions for --into group support
- Reconcile tests use bare name as store key (not group/name)
- updatable_test uses MetadataStore directly instead of WriteMeta dual-write
- Tracked repos marked with Tracked: true in store
- All unit + integration tests pass (make check green)
- Dual-write in WriteMeta: also writes to .metadata.json for backward compat
- Migration looks in parent dir for registry.yaml
- Group uninstall matches entries by Group field + full path
- Sync test uses MetadataStore instead of registry.yaml
- All integration tests pass (0 FAIL)
Replace every remaining call to the old per-skill metadata API
(ReadMeta, RefreshMetaHashes, config.LoadRegistry) with the centralized
MetadataStore across 10 files:
Server handlers:
- handler_check.go: use s.skillsStore.Get() instead of ReadMeta
- handler_check_stream.go: same pattern as handler_check.go
- handler_skills_batch.go: use s.skillsStore.RefreshHashes() + Save()
CLI commands:
- check.go: load store once in collectCheckItems, use MetadataEntry
- doctor.go: load store once in checkSkillIntegrity
- list.go: load store once in buildSkillEntries (replaces parallel ReadMeta)
- uninstall.go: use skillsStore for display/dry-run/finalize
- uninstall_project.go: same pattern, remove config.LoadRegistry
- update_batch.go: pruneRegistry now uses MetadataStore
Hub:
- hub/index.go: load store once in BuildIndex
The only remaining ReadMeta call is in a test file
(search_batch_meta_roundtrip_test.go) which tests the shim itself.
ComputeFileHashes now skips both .skillshare-meta.json and
.metadata.json. WriteMeta, ReadMeta, HasMeta, NewMetaFromSource,
RefreshMetaHashes marked as deprecated.
LoadMetadataWithMigration auto-detects old format on first load:
reads registry.yaml entries, merges sidecar .skillshare-meta.json
fields, writes unified .metadata.json, cleans up old files.
Idempotent — skips migration if .metadata.json already exists.
Introduces MetadataEntry (merges SkillMeta + RegistryEntry) and
MetadataStore (map-based container with Set/Get/Remove/Has/List).
This is the foundation for centralized .metadata.json files.
- CheckAgents uses recursive discovery via resource.AgentKind{}.Discover()
so nested agents (e.g. demo/code-reviewer.md) are found correctly
- Add --group/-G flag to update, check, and uninstall agents commands
with shared validateAgentGroups/matchesAnyGroup helpers
- Fix TUI project-mode dispatch: call cmdUpdateAgentsProject and
cmdUninstallAgents directly instead of passing 'agents' keyword to
handlers that don't understand it
- TUI confirmation overlay shows correct command with 'agents' keyword
and confirmKind field tracks skill vs agent
- TUI toggleDisabled (E key) writes to .agentignore for agents instead
of .skillignore
- Agent Discover now marks .agentignore matches as Disabled=true instead
of skipping them, so disabled agents appear in list with [disabled] tag
- Sync filters out disabled agents via resource.ActiveAgents()
- auditSkillByName uses scanPathTarget to support single-file agent audit
- Uninstall agents display uses RelPath (e.g. demo/tutor) instead of
frontmatter name (e.g. Python Tutor Expert)
When extras has an entry named 'agents' whose target paths overlap with
the resolved agent target paths from targets.yaml, the extras targets
are skipped with a warning — the agents sync system takes priority.
Detection uses dual conditions: extras name == 'agents' AND resolved
path overlap. Non-'agents' extras targeting agent paths are unaffected.
Agents source must exist with actual files; empty/missing source means
no overlap (extras sync normally).
Also fixes:
- CheckAgents now recurses into subdirectories via resource.AgentKind
- update agents resolves nested agent names via filepath.Base
- filterAgentCheckResults matches both full path and basename
- Add Tab/Shift+Tab to cycle All/Skills/Agents tabs with count badges
- Tab bar renders at top with bold+underline cyan active, dim inactive
- Tab acts as pre-filter composing with text filter via AND logic
- Cache tab-filtered items in applyFilter() to avoid per-frame recomputation
- Add tabNoun() method to consolidate noun switches across title/filter bar
Agent install --into support:
- Support --into flag for agent install (CLI, server, project mode)
- Support --into=value syntax in addition to --into value
- Server handler_skills uses recursive AgentKind.Discover() for nested agents
- Fix agent metadata read path: use file basename instead of frontmatter name
- Sync --all flag now includes agent sync (not just extras)
Agent content viewer:
- Agents render full-width without sidebar (single .md file, no tree needed)
- Simplified help text and keyboard handling for agent content view
Agent uninstall fixes:
- Use discovery-based resolution instead of hardcoded name+.md path lookup
- Support matching by Name, FlatName, RelPath, or trimmed RelPath
- Compressed confirmation display (list format, max 20 shown)
UI polish:
- Help bar keys highlighted in dim cyan, descriptions in dim gray
- Align 'No items.' text with list title via PaddingLeft(2)
Without this, installDiscoveredAgents in project mode falls back to
the global agents path (~/.config/skillshare/agents/) instead of the
project agents path (.skillshare/agents/).
Validates the full agent workflow: install mixed repo (skills + agents)
then sync all — verifying skills go to skills targets, agents go to
agent-capable targets, agents are excluded from targets without agents
path, and the skip warning mentions the target name.
Uses 'sync all' since plain 'sync' only syncs skills by design.
Both syncAgentsGlobal and syncAgentsProject now collect target names
where agentPath is empty and print a summary warning after the sync
summary line. This makes it visible to users which targets were
silently skipped, helping them configure agents paths if desired.
Mixed repos containing both skills/ and agents/ directories previously
only installed skills, silently ignoring agents. Now after every skill
install exit point, discovered agents are also installed to the agents
source directory.
- Add installDiscoveredAgents helper that installs agents post-skills
- Update 'Found' message to show agent count in mixed repos
- Call helper at all 4 skill install exit points in handleGitInstall
- Add integration test for mixed-repo install scenario
Pure-agent repos now show a checklist TUI for selecting which agents
to install (matching the skill install flow). Supports:
- Single agent: direct install (no TUI)
- Multi-agent: interactive checklist TUI (space/a/enter)
- --all/--yes: install all without prompt
- -a name1,name2: filter by name without prompt
- --dry-run: preview list
- Non-TTY: error with hint to use flags
- Batch progress: spinner (<=20) or progress bar (>20)
- Results display: installed/failed/skipped sections
When a repo has no SKILL.md files but contains .md agents (discovered
via Rule 4 fallback in discovery layer), the CLI now installs them
instead of showing 'No skills found'.
Adds handleAgentInstall() which:
- Respects --agent name filter
- Uses InstallAgentFromDiscovery() (same as UI flow)
- Supports --dry-run and --force
- Shows next-steps hint to run 'sync agents'
- TestList_Agents_KindFilter_NoTUI: verifies list agents/all/default
kind filtering works correctly in --no-tui mode
- TestTrash_MergedList_IncludesAgents: verifies uninstalled agents
appear in trash agents list --no-tui output
Merge agent diffs into skill diff results so both appear together
in the diff TUI. Agent entries display a cyan [A] badge prefix
in the detail panel's category listings.
Changes:
- Add mergeAgentDiffsGlobal/mergeAgentDiffsProject helpers that
compute agent diffs and merge them into per-target skill results
- Call merge helpers in cmdDiffGlobal and cmdDiffProject before
TUI/output rendering
- Build agent name set in buildDiffDetail and render [A] badge
for agent entries in category expansion
- Fix categorizeItems to handle agent-specific reasons
('not in target' → New, 'local file' → Local Only)
Add [A] badge to agent backup entries in the target list, and resolve
the correct agent target path when restoring. Agent backups (entries
ending with -agents) now look up AgentsConfig or fall back to builtin
DefaultAgentTargets for path resolution, both in the restore action
and in the detail/diff panels.
Agents are single .md files, not directories. The content viewer now:
- Detects agent vs skill via contentKind field on the model
- Renders agent .md content directly (no directory walk)
- Shows a single-file tree entry for the agent
- Resolves file paths from agentsSourcePath for agents
Add -p/--project support to 'backup agents' and 'restore agents' commands.
Project-mode backups are stored under .skillshare/backups/ (parallel to
.skillshare/trash/).
Backup engine changes:
- Add ProjectBackupDir(), CreateInDir(), ListInDir() to internal/backup
- Add RestoreLatestInDir(), FindBackupsForTargetInDir(),
GetBackupByTimestampInDir() to restore.go
- Existing global functions become thin wrappers (zero caller churn)
Command layer changes:
- Allow project mode through for kind=agents in cmdBackup/cmdRestore
- Auto-detect project mode when .skillshare/config.yaml exists
- Refactor backup_agents.go with resolveAgentBackupContext() to
resolve backup dir + agent targets per mode
Skills backup in project mode remains unsupported (error unchanged).
Add comprehensive agents_commands_runbook.md covering all agent CLI
commands: list, sync, status, diff, collect, uninstall, trash, update,
backup, and doctor (30 steps).
Fix 18 previously failing runbooks:
- Add workdir: $HOME to mdproof.json to prevent workspace pollution
from project mode auto-detection
- Fix jq assertions using positional index to use select(.name == ...)
- Fix extras_flatten legacy agents/ dir conflict (rm in cleanup)
- Fix auto_create_target_dir sed insertion and Will/Would wording
- Fix uninstall_sync_orphan config indentation for migrated format
- Fix universal_target_path grep pattern (name vs global_name)
- Fix uninstall_all_glob registry.yaml filter in verify step
- Fix target_naming grep for actual CLI warning output
- Fix registry_yaml_split anchored grep for top-level skills:
- Fix skillignore_source_discovery stdout suppression and jq filter
- Fix ui_base_path: use pre-built binary, PID files, high ports,
redirect server log to stderr to keep JSON pure
- Fix extras init redirect to suppress ANSI warnings in JSON steps
From 3-agent review (reuse, quality, efficiency):
Bug fix:
- syncAgentsProject: use resolveProjectAgentTargetPath instead of
inline path resolution (~ was not expanded for absolute paths)
Deduplication:
- Extract syncAgentTarget() shared by global + project sync loops
(eliminates 30-line copy-paste)
- Extract renderAgentCheck() shared by project + global check
(eliminates duplicate rendering block)
- Consolidate countLinkedAgents → delegates to countAgentLinksAndBroken
Efficiency:
- Use DirEntry.Type() instead of os.Lstat in diff_agents.go and
doctor_agents.go (saves one syscall per .md file)
Cleanup:
- Remove dead start param from cmdCollectAgents
- Remove unused imports
Net: -76 lines.
Remove all "not yet supported in project mode" errors. Every command
that supports agents in global mode now also supports project mode:
- status -p agents: shows project agent source + per-target status
- status -p all: shows both skills and agents
- check -p agents: checks agent status from .skillshare/agents/
- diff -p agents: computes agent diffs (missing/orphan per target)
- diff agents (global): also now fully implemented via diffGlobalAgents
- collect -p agents: collects local agents from project targets
- audit -p agents: scans .skillshare/agents/ for security patterns
New file: diff_agents.go — shared agent diff logic for both modes
(computeAgentDiff, diffProjectAgents, diffGlobalAgents).
11 new integration tests covering all 5 commands in project mode.
Total agent tests: 56.
7 new integration tests covering:
- trash agents empty / delete
- uninstall agents in project mode (fix: wire kind into project dispatch)
- check all (combined skill + agent)
- sync agents skips targets without agent path
- list all --json verifies kind field on every entry
- status agents --json with target details
Total agent tests: 45 (38 + 7).