Adapters

Adapters

Weave Skills uses lightweight filesystem-native adapters to expose shared operational capabilities across multiple AI tools.

The architecture intentionally favors:

filesystem-native interoperability

rather than:

• orchestration runtimes
• generated integration systems
• platform-owned ecosystems
• or centralized synchronization layers

Core Principle

The shared skill surface should remain:

portable
lightweight
filesystem-native

across tools and workflows.

The repository intentionally avoids:

- vendor lock-in
- runtime ownership
- platform coupling
- and duplicated skill surfaces

Shared Skill Surface

Recommended shared skill container:

.agents/skills

Optional namespaced layout:

.agents/skills/weave-skills

This convention intentionally remains:

• optional
• portable
• adapter-friendly
• and lightweight

The repository does NOT define .agents as a formal standard.

Instead, the directory acts as:

a shared portable skill surface

across multiple local-first AI workflows.

Why Shared Skill Surfaces Matter

Without shared skill surfaces, workflows often produce:

• duplicated skills
• fragmented overlays
• inconsistent behavior
• adapter drift
• and operational divergence

A shared filesystem-native surface improves:

• interoperability
• continuity
• consistency
• and operational portability

Filesystem-Native Composition

Composition is intentionally handled through filesystem primitives.

Examples include:

• symbolic links
• junctions
• aliases
• bind mounts
• and shared filesystem mappings

This preserves:

• filesystem authority
• operational simplicity
• lightweight composition
• and deterministic behavior

Example Topology

Recommended topology:

                 ┌────────────────────┐
                 │  .agents/skills    │
                 └─────────┬──────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼

.cursor/skills   .claude/skills   .windsurf/skills

Each adapter exposes the same shared skill surface without duplicating the underlying skills.

Example Symlink

Example:

ln -s ../../.agents/skills .cursor/skills

Result:

.cursor/skills
    │
    └── .agents/skills

The same approach may be used for multiple tools simultaneously.

Adapter Philosophy

Adapters intentionally remain:

thin filesystem mappings

NOT:

• orchestration runtimes
• synchronization systems
• ownership layers
• semantic coordinators
• or generated integration frameworks

This became one of the strongest architectural stabilizers of the system.

Adapter Isolation

Each tool preserves its own:

• runtime behavior
• execution model
• contextual heuristics
• and operational environment

The shared skill surface only provides:

• portable operational capabilities
• contextual operational guidance
• and workflow continuity surfaces

This separation preserves bounded interoperability.

Tool Compatibility

The shared filesystem-native model is compatible with tools such as:

• Claude Code
• Cursor
• Continue
• Cline
• Codex
• Gemini CLI
• GitHub Copilot
• OpenCode
• RooCode
• Windsurf

The repository intentionally avoids platform-specific ownership semantics.

Why The System Avoids Runtime Adapters

The architecture intentionally avoids:

• generated runtime bridges
• synchronization daemons
• orchestration layers
• centralized adapter registries
• and platform-owned interoperability systems

These approaches often produce:

• complexity inflation
• runtime coupling
• operational fragility
• and ecosystem fragmentation

Instead, the system intentionally prioritizes:

simple filesystem-native composition

Workspace Locality

Adapters preserve repository locality.

The shared skill surface remains embedded directly inside real repositories.

This preserves:

• operational continuity
• implementation grounding
• filesystem awareness
• and contextual locality

across tools.

Long-Running Continuity

One of the strongest goals of the adapter model is preserving:

long-running operational continuity

across:

• multiple tools
• multiple agents
• multiple sessions
• and long-running engineering workflows

without duplicating operational overlays.

Recommended Repository Layout

Example:

repository/
│
├── .agents/
│   └── skills/
│       └── weave-skills/
│
├── .cursor/
│   └── skills -> ../../.agents/skills
│
├── .claude/
│   └── skills -> ../../.agents/skills
│
└── .windsurf/
    └── skills -> ../../.agents/skills

This preserves:

• a single shared skill surface
• adapter isolation
• filesystem authority
• and lightweight interoperability

Operational Boundaries

Adapters intentionally DO NOT:

• mutate runtime behavior
• own repository semantics
• preserve invariants
• semanticize repositories
• or coordinate contextual state globally

Adapters only expose:

- shared operational overlays
- contextual reasoning surfaces
- and portable capability layers

inside workflows.

Relationship To Runtime

The runtime remains authoritative.

The runtime preserves:

• deterministic-safe editing
• canonical serialization
• normalization
• validation
• and semantic consistency

Adapters intentionally remain external to runtime authority.

Relationship To Semantic Scope

Adapters do NOT redefine semantic scope.

Recommended semantic root:

.context/notes

Core principle:

semantic scope != filesystem scope

Adapters expose operational overlays without altering semantic boundaries.

Architectural Philosophy

The adapter architecture intentionally favors:

small
portable
filesystem-native
lightweight
bounded

rather than:

platform-owned
runtime-heavy
orchestration-driven
ecosystem-centric

This became one of the strongest convergence points of the architecture.

Related Documents

• Architecture
• Operational Model
• Semantic Scope
• Runtime Boundaries
• Contributing Skills