[Feature] AIShare: centralized AI resource hub beyond skills (scripts, docs, prompts, IDE/MCP configs) with selective downstream sync

[chaosky]

Summary

Today skillshare solves skill distribution well (manifest → install → sync to IDE targets). In real team/org setups, teams need a single centralized hub for all AI-facing project assets—not only skills—and downstream projects need to import only what they need, similar to how skillshare already supports per-skill selection.

This issue proposes extending skillshare (or a sibling project, e.g. AIShare) to manage a broader set of AI resources from one repository, with the same install/sync/update workflow teams already use for skills.

---

Motivation / Problem

We operate a mono-repo style example consumer (example-app-monorepo) as the reference downstream project. Skills are centralized in a dedicated hub repo (example-ai-hub) and consumed via skillshare HTTP sources. Even with that, we still duplicate and manually maintain many other AI resources per project:

Resource type	Typical locations today	Pain
Skills	.skillshare/skills/ → .agents/skills/, IDE mirrors	Works via skillshare; clutters repo root; upstream skill management is awkward (see below)
Shared scripts	scripts/ops/, skill scripts/	Split between repo scripts vs skill scripts; cross-import via sys.path
Docs / KB	docs/knowledge-base/, docs/agent-workflows/	Not shareable; each repo copies or drifts
Prompts / agent instructions	AGENTS.md, backend/AGENTS.md	No distribution mechanism
IDE / tool configs	.cursor/, .github/copilot-instructions.md, other dot-folders	skillshare extras can sync rules/commands locally, but no hub → project install for MCP packs, Copilot instructions, or multi-IDE bundles
Project bindings	.skillshare/project-bindings.yaml	Schema exists in hub repo, but no partials/profiles/overrides from hub

Onboarding today requires many manual steps: env secrets, project-bindings.yaml, skillshare install/sync, MCP JSON, IDE rules, Copilot instructions, KB paths in AGENTS.md—not one coherent “sync AI assets” command.

---

Proposal: AIShare (extend skillshare or new first-class module)

A centralized AI resource repository (hub) that downstream projects consume selectively.

Hub repo layout (example)

ai-hub/                          # org-level or team-level hub (e.g. example-ai-hub, extended beyond skills-only)
├── skills/                      # existing skillshare layout
│   ├── deployment-observability/
│   └── vendor/                  # optional: git submodules for upstream skills
│       └── superpowers/         # submodule → https://github.com/obra/superpowers
├── scripts/                     # shared ops/tool scripts (not tied to one skill)
│   ├── ops/
│   └── tools/
├── docs/                        # shared knowledge base modules
│   ├── knowledge-base/
│   └── architecture/
├── prompts/
│   ├── AGENTS.md                # base agent contract
│   └── modules/                 # optional composable prompt fragments
├── bindings/
│   ├── project-bindings.schema.yaml
│   └── profiles/                # e.g. default-dev-test.yaml partials
└── targets/                     # IDE/tool config templates
    ├── cursor/
    │   ├── rules/
    │   └── mcp.json.template
    ├── kiro/                    # example: another IDE target supported by skillshare
    │   ├── steering/
    │   └── settings/mcp.json.template
    ├── copilot/
    │   └── copilot-instructions.md
    └── intellij/
        └── ...                  # IDE AI settings when applicable

Downstream project keeps only deltas (project-specific pipelines, k8s cluster/namespace bindings, domain KB) and syncs the rest from hub.

---

Resource types & requirements

1. Skills (existing + enhancements)

Keep current skillshare model: manifest, install, sync, targets (universal, kiro, etc.), --track, --force, project/global source dirs (.skillshare/skills/ or ~/.config/skillshare/skills/).

Add: git submodule support in hub + install path

We want upstream skills as git submodules inside the hub repo because:

• Some upstream skill versions are degraded for our workflow; we maintain a fork/pinned copy.
• Submodule makes upstream updates explicit (git submodule update) and reviewable.
• Hub can re-export flat skill trees to downstream via install/sync.

Current blocker (observed in skillshare ~0.20.x):

• skillshare install uses plain git clone without --recurse-submodules.
• If skills/foo/ is a submodule gitlink, HTTP/sparse install yields empty dirs (no SKILL.md).
• Official migration doc recommends exporting submodule contents, not relying on submodules in install sources.

Requested behavior:

• Hub maintainer: manage upstream skills as submodules (or subtree) in hub repo.
• skillshare/AIShare install: resolve submodules (or materialize vendored copy) so downstream always gets full files.
• Optional: skillshare vendor sync from upstream with lock file / commit pinning (we built this manually outside skillshare today).

2. Scripts

Shared operational scripts (Kubernetes helpers, CI/CD wrappers, MCP servers, etc.) that are not embedded in a single skill.

Requirements:

• Manifest entry per script bundle or per script package (like skills).
• Install under project .skillshare/ (or a configurable project path); global/org scripts could live beside ~/.config/skillshare/skills/.
• Sync to tool-specific targets if needed (e.g. PATH shim, documented invocation from repo root).
• Selective import: only install listed script packages.

3. Docs (knowledge base)

Shared KB modules (runbooks, learning logs, architecture summaries) referenced from AGENTS.md and skills.

Requirements:

• Install/sync docs modules under .skillshare/docs/<module>/ (project) or a hub-defined path, or merge into project docs/ with conflict policy.
• Support partial modules (e.g. only knowledge-base/index.md + learning.md, not an entire project history).
• Optional: symlink vs copy mode (like skills targets).

4. Prompts (AGENTS.md and fragments)

Base agent instructions shared across repos; projects overlay local sections.

Requirements:

• Install base AGENTS.md (or prompts/AGENTS.base.md) with merge strategy:
  • replace / prepend / append / merge-sections (by heading).
• Composable prompt fragments (prompts/modules/*.md).
• Sync to root AGENTS.md and/or tool-specific instruction files.

5. IDE / AI tool configuration (hub install + templates)

skillshare already syncs rules, commands, prompts from extras/ to targets such as ~/.cursor/rules/ (extras docs). The gap is remote hub install and shared templates across consumer repos:

Target	skillshare today	AIShare gap
Cursor rules	extras → .cursor/rules/ (symlink/copy)	Install targets/cursor/rules/ from hub manifest
Cursor MCP	manual / per-repo .cursor/mcp.json	mcp.json.template → render with secret env vars
Kiro steering / MCP	per-repo .kiro/	hub targets/kiro/ bundle, selective import
GitHub Copilot	.github/copilot-instructions.md	hub template + merge/install
IntelliJ / JetBrains AI	TBD	hub targets/intellij/ when format is known

Requirements:

• Same manifest + selective import as skills (install from hub, not only local extras init).
• Template variables for secrets (MCP env → local secrets dir, not committed).
• Dedupe: one hub definition → multiple IDE targets (reuse skillshare target/extras sync mechanics where possible).

---

Downstream consumption model

Extend skillshare project manifest (.skillshare/config.yaml) with additional resource types:

# PROJECT-ROOT/.skillshare/config.yaml
hub: http://git.example.com/org/ai-hub

resources:
  skills:
    - name: deployment-observability
      source: .../skills/deployment-observability
    - name: brainstorming
      source: .../skills/vendor/superpowers/skills/brainstorming
  scripts:
    - name: postgres-readonly-mcp
      source: .../scripts/tools/mcp/postgres-readonly
  docs:
    - name: kb-core
      source: .../docs/knowledge-base
  prompts:
    - name: agents-base
      source: .../prompts/AGENTS.md
      merge: prepend
  configs:
    - name: cursor-pack
      target: cursor
      source: .../targets/cursor

bindings:
  profile: default-dev-test
  overlay: .skillshare/project-bindings.yaml

CLI (conceptual — ideally extends skillshare, not a parallel tool):

skillshare install -p          # existing: skills from manifest
aishare install -p             # or skillshare: install scripts/docs/prompts/configs from hub
skillshare sync --all          # existing: skills + agents + extras
aishare install scripts/postgres-readonly-mcp -p

About project-bindings.yaml

Hub skills are project-agnostic; each consumer repo keeps Layer 2 structured config at .skillshare/project-bindings.yaml (committed; non-secrets). Skill scripts discover it by walking up from cwd.

Section	Purpose
paths.*	Doc/KB paths in the consumer repo (e.g. kb_index, agent workflow plans/logs, agents_md)
config_center.*	CLI env alias → remote config namespace/tenant (any config server: Spring Cloud Config, Consul, etcd, …)
deploy.*	CI/CD --env profiles (cluster, namespace, kube context), pipeline → workload map

Layer 1 (passwords, tokens, base URLs) stays in local env files (.envrc, .env.local, CI secrets)—not in this YAML.

AIShare would optionally ship hub profiles that merge with the consumer overlay, so teams only maintain project-specific deltas.

Note: Binding keys are vendor-neutral (config_center.*, deploy.*). Examples avoid region- or vendor-specific product names.

---

Reference implementation (real-world)

We can provide a reference hub + consumer setup based on:

• Hub (example-ai-hub): custom skills, vendored third-party skills, schema, consuming-project docs.
• Consumer (example-app-monorepo): .skillshare/config.yaml, .skillshare/project-bindings.yaml; repeated MCP/rules across IDEs; local KB under docs/.

This is the concrete case driving the request—not hypothetical.

---

Non-goals / constraints

• Secrets stay local: hub ships templates and env var names; credentials remain in local env / CI secrets (Layer 1).
• Prod safety: ops skills/scripts may restrict environments; hub should not weaken existing guardrails.
• Not replacing project-specific history: agent plans/ / activity-logs/ remain per-project, not synced from hub.

---

Alternatives considered

1. Multiple repos + copy/paste — current state; high drift.
2. Monorepo only — doesn’t scale across many services/repos.
3. Git submodules in consumer repos — poor DX for skillshare HTTP install; agents don’t get files.
4. Flat vendor only (no submodule) — works but upstream management is manual.

---

Optional: project-local path layout

Optional add-on — not part of the core AIShare feature request. Project mode today uses .skillshare/ at the repo root. This section asks whether project mode could optionally use a cleaner in-repo layout:

Today (skillshare project mode)	Optional project-local layout
.skillshare/config.yaml	.config/skillshare/config.yaml
.skillshare/project-bindings.yaml	.config/skillshare/project-bindings.yaml
.skillshare/skills/ (gitignored clones)	.local/share/skillshare/skills/
.skillshare/backups/	.local/state/skillshare/backups/

Example (optional — not a replacement for global ~/.config/skillshare/):

example-app-monorepo/
├── .config/skillshare/
│   ├── config.yaml
│   └── project-bindings.yaml
├── .gitignore                    # ignore .local/
└── docs/                         # project-specific KB only

If adopted, skillshare would need configurable project root paths; default should remain .skillshare/ for compatibility.

---

Why an issue, not a PR?

I am opening a detailed feature issue rather than a pull request, on purpose:

In AI-assisted / AI-driven development, upstream projects benefit from a small, focused maintainer group that owns design, API shape, and code quality. Wider adoption comes from clear requirements and real-world constraints (like this document), not from many parallel PRs that are hard to review and may diverge from the maintainers’ roadmap.

I can help validate designs and test betas; I prefer collaboration through issues + maintainer PRs over fragmenting the codebase across many authors.

---

Related

• skillshare README — global XDG paths, extras, project mode
• skillshare Project Setup / extras configuration / migration from git submodules docs
• Agent Skills spec (skills remain compatible)

I can contribute reference manifests, schema drafts, or a minimal POC consumer repo if useful.

[chaosky]

Related issue
#95 #133 #135 #146 #202

[runkids]

Thanks for framing it this way. Large PRs for broad product/API changes are difficult to review and often stall, so issue-first collaboration works much better for this kind of proposal.

I’ll keep this open as a roadmap/design discussion. There are several interesting points here, and I’d like to revisit it when I have more time to think through the scope and tradeoffs properly.

For now, concrete real-world examples, fixtures, and validation cases would be the most useful inputs. I’m not ready to commit to a timeline or direction yet, but this is useful context to keep around.