⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

Agent-Scoped Local Retrieval

ys-c-23@ys-c-23⭐ 0 stars· last commit 7mo ago· 0 open issues

Build boundary-first local retrieval for OpenClaw with explicit corpora, deny-by-default agent access, separate memory layers, and a validated minimal demo path.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 0 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Agent-Scoped Local Retrieval

A boundary-first local retrieval skill for OpenClaw workspaces.

This repository packages a reusable local-first retrieval pattern for multi-agent environments with:

  • explicit corpus boundaries
  • deny-by-default agent access
  • prerequisite gating before runtime execution
  • maintenance-aware refresh behavior
  • explicit maturity labels for honest validation claims

It includes a validated minimal demo path and a bootstrap pattern for adapting the architecture to a real OpenClaw workspace, without claiming turnkey production retrieval for arbitrary environments.

Why this exists

Many local RAG setups start with one simple idea: index everything and add search.

That works for quick demos, but it breaks down in longer-running workspaces. The first problems are often not ranking quality. They are:

  • personal memory mixed with reusable workspace knowledge
  • unclear retrieval boundaries
  • agents getting broader access than they should
  • noisy recall from over-broad indexing
  • refresh workflows that default to blind full rebuilds
  • runtime dependencies discovered too late, after execution has already started failing
  • maturity claims that outrun what has actually been tested

workspace-local-retrieval packages a different default.

Core ideas

  • Separate personal memory from workspace retrieval
  • Use allowlisted corpora instead of indexing everything
  • Enforce deny-by-default access per agent
  • Keep one stable retrieval interface for callers
  • Treat maintenance and selective refresh as part of the design
  • Gate execution on prerequisite checks
  • Classify maturity honestly using explicit validation rules

The emphasis is not only retrieval quality. It is retrieval architecture, runtime discipline, and validation honesty.

What the skill includes

  • a workflow-oriented SKILL.md
  • sanitized starter templates for corpora, agent allowlists, memory boundaries, and backend config
  • reference docs for:
    • privacy and boundaries
    • agent scoping
    • interface contracts
    • maintenance patterns
    • dependency and platform guidance
    • preflight and install policy
    • quickstart guidance for adapting the pattern to a real workspace
    • validation contract
    • anti-overclaim guidance
    • design rationale
    • publish readiness
  • a conservative bootstrap script that generates starter config without ingesting private data automatically
  • a runnable prerequisite check script for Python / Node / SQLite / FTS5 / embedding-backend readiness
  • a sanitized demo corpus plus minimal index/search/smoke-test scripts for a closed-loop proof path
  • a sanitized demo walkthrough for public explanation and validation

Who this is for

This skill is useful if you are building:

  • local AI assistants
  • multi-agent workspaces
  • privacy-sensitive local RAG systems
  • agent infrastructure with scoped retrieval access
  • long-running retrieval workflows that need maintenance discipline

What this skill is not

This is not:

  • a hosted vector database
  • a turnkey enterprise retrieval platform
  • a benchmark package for ranking quality
  • a substitute for careful corpus design
  • a fully validated closed-loop retrieval system by default

It is a reusable architectural pattern and starter kit.

Maturity labels

Use these labels honestly:

  • architecture-only: boundaries, templates, and contracts exist, but no real retrieval loop has been proven
  • minimally runnable: a safe demo path can ingest a small corpus, build an index, and answer at least one query
  • fully validated: the minimal closed loop exists and the validation contract passes

Do not call the repo fully validated, end-to-end, production-ready, or plug-and-play unless the actual evidence supports that claim.

Repository contents

workspace-local-retrieval/
  SKILL.md
  assets/
    demo-corpus/
  references/
    agent-scoping.md
    anti-overclaim.md
    dependencies-and-platforms.md
    design-rationale.md
    example-templates.md
    interface-contract.md
    maintenance-patterns.md
    minimal-e2e-demo.md
    preflight-and-install-policy.md
    privacy-and-boundaries.md
    publish-readiness-checklist.md
    runtime-layout.md
    sanitized-demo.md
    validation-contract.md
  scripts/
    bootstrap_workspace_retrieval.py
    build_minimal_index.py
    check_retrieval_prereqs.py
    install_prereqs_linux.sh
    install_prereqs_mac.sh
    install_prereqs_windows.ps1
    run_minimal_smoke_tests.py
    search_minimal_index.py
    setup_demo.sh

What works today

Today this repository can help a user:

  • check local prerequisites
  • install baseline prerequisites on macOS and Linux with helper scripts
  • install baseline prerequisites on Windows via a winget-based PowerShell helper
  • run a validated minimal retrieval demo
  • bootstrap sanitized starter config for adapting the pattern to a real workspace

A safe public summary is:

This repo includes a validated minimal demo path and a bootstrap pattern for adapting the retrieval architecture to a real OpenClaw workspace.

What it does not claim today:

  • turnkey production retrieval for arbitrary workspaces
  • fully automated semantic retrieval setup
  • zero-judgment corpus design or policy design

5-minute runnable path

For a technically comfortable first-time user, the fastest path is:

  1. Enter the skill folder:
    cd workspace-local-retrieval
    
  2. Check prerequisites:
    python3 scripts/check_retrieval_prereqs.py
    
  3. If dependencies are missing:
    • macOS:
      bash scripts/install_prereqs_mac.sh
      
    • Linux:
      bash scripts/install_prereqs_linux.sh
      
    • Windows (PowerShell):
      powershell -ExecutionPolicy Bypass -File .\scripts\install_prereqs_windows.ps1
      
  4. Run the minimal closed-loop demo:
    bash scripts/setup_demo.sh
    

This path validates a small local retrieval system with:

  • prerequisite gating
  • bootstrap-ready config patterns
  • SQLite FTS5 indexing
  • scoped search
  • smoke-test coverage

Adapting to a real workspace

After the demo path passes, the next step is to adapt the pattern to your own workspace.

Use:

  • scripts/bootstrap_workspace_retrieval.py to generate starter config
  • references/quickstart-real-workspace.md for the first real workspace path

The recommended approach is:

  • start with a narrow lexical baseline
  • define corpora before indexing
  • keep deny-by-default agent access
  • validate one real workflow before broadening scope

Suggested usage

  1. Run the prerequisite check first.
  2. If required dependencies are missing, stop and either:
    • report the skill as currently unavailable, or
    • create an OS-aware install plan if environment prep is allowed.
  3. Bootstrap sanitized retrieval config templates.
  4. Define explicit corpora.
  5. Define deny-by-default agent access.
  6. Keep personal memory and workspace retrieval as separate layers.
  7. Add a stable retrieval wrapper.
  8. Add freshness checks and selective refresh.
  9. Validate using the maturity labels and validation contract.

Why the public version is sanitized

This repository is intentionally generalized.

It does not include:

  • private workspace paths
  • live user data
  • private memory files
  • credentials or tokens
  • generated indexes or embeddings
  • environment-specific runtime state

The goal is to publish the pattern, not leak the original workspace.

Publishing

For ClawHub distribution, package and upload the .skill artifact.

For GitHub distribution, publish the skill folder plus a small amount of explanatory material such as this README and launch copy.

License

This project is licensed under the MIT License. See LICENSE.

Contact / discussion

If you are working on local-first assistants, agent infrastructure, retrieval governance, or privacy-aware multi-agent systems, feel free to adapt the pattern and compare notes

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • workspace-local-retrieval/SKILL.md6.9 KBupstream ↗
    ---
    name: Agent-Scoped Local Retrieval
    description: Build boundary-first local retrieval for OpenClaw with explicit corpora, deny-by-default agent access, separate memory layers, and a validated minimal demo path.
    ---
    
    # Workspace Local Retrieval
    
    Package retrieval as architecture, not ad-hoc glue.
    
    This skill exists for a common failure mode in local RAG systems: indexing grows faster than boundary discipline. The result is usually a system that can sometimes retrieve relevant text, but cannot clearly answer:
    - what should be searchable
    - which agent should see which corpus
    - what belongs in personal memory versus workspace knowledge
    - how freshness should be maintained over time
    - what has actually been validated versus merely sketched
    
    Prefer this skill when the goal is **workspace knowledge retrieval**, not personal memory recall. Keep those layers separate.
    
    ## Core workflow
    
    1. **Run a preflight gate before any retrieval work**
       - Run `scripts/check_retrieval_prereqs.py` before bootstrap, indexing, embedding refresh, or search.
       - Treat missing required prerequisites as a hard stop.
       - If the user wants direct setup help, use `scripts/install_prereqs_mac.sh` on macOS or `scripts/install_prereqs_linux.sh` on Linux as a first-pass installer, then rerun preflight.
       - Read `references/dependencies-and-platforms.md` when deciding what is required on the current OS.
       - Read `references/preflight-and-install-policy.md` when deciding whether to stop, warn, or produce an installation plan.
    
    2. **Decide the boundary model first**
       - Use built-in memory tools for personal continuity (`MEMORY.md`, `memory/*.md`).
       - Use this skill's retrieval pattern for workspace knowledge, docs, skills, plans, schemas, and agent-specific materials.
       - Do not merge personal notes into a general retrieval corpus unless the user explicitly wants that and understands the privacy tradeoff.
       - Read `references/privacy-and-boundaries.md` before writing corpus config.
    
    3. **Design corpora and agent access explicitly**
       - Split knowledge into small allowlisted corpora.
       - Use deny-by-default agent retrieval policy.
       - Keep separate memory-boundary rules for personal memory vs domain memory.
       - Read `references/agent-scoping.md` when mapping corpora and memory roots to agents.
    
    4. **Bootstrap templates safely**
       - Run `scripts/bootstrap_workspace_retrieval.py --dest <dir>` to generate sanitized starter templates.
       - The script creates template config files only. It does not read external services, call the network, or ingest private data.
       - For first-run validation, use `scripts/setup_demo.sh` to execute the minimal demo path before adapting the pattern to a real workspace.
       - Read `references/runtime-layout.md` before claiming the setup is runnable.
    
    5. **Implement one stable retrieval entrypoint**
       - Keep one wrapper responsible for agent-facing search and corpus allowlist checks.
       - Keep indexing, embeddings, and scoring internals behind the wrapper.
       - Read `references/interface-contract.md` for the recommended search-wrapper contract.
    
    6. **Add maintenance-aware refresh behavior**
       - Track corpus fingerprints or file signatures.
       - Prefer selective refresh when only a small set of files changed.
       - Fall back to full rebuild only when needed.
       - Read `references/maintenance-patterns.md` for a production-friendly approach.
    
    7. **Validate before making maturity claims**
       - Do not claim retrieval is ready because indexing succeeded once.
       - Read `references/validation-contract.md` to classify the result as `architecture-only`, `minimally runnable`, or `fully validated`.
       - Read `references/anti-overclaim.md` before writing publish-facing or user-facing maturity claims.
       - When the user wants proof of a runnable closed loop, read `references/minimal-e2e-demo.md` and run the demo scripts rather than describing a hypothetical future validation plan.
    
    ## Hard truth rules
    
    - No required prerequisites, no execution.
    - No real closed loop, no `end-to-end` claim.
    - No smoke-test suite, no `fully validated` claim.
    - No reproducible evidence, no strong marketing language.
    - If uncertain, downgrade the maturity label rather than stretch it.
    
    ## Recommended file layout
    
    Use this skill as a pattern, not a rigid requirement.
    
    ```text
    retrieval/
      config/
        corpora.json
        agent_corpora.json
        agent_memory.json
        backend.json
      scripts/
        workspace_search.mjs
        build_index.py
        build_embeddings.mjs
        retrieval_status.py
        refresh_incremental.py
      indexes/
        workspace_retrieval.sqlite
    ```
    
    If the workspace already has a retrieval system, adapt the layout instead of forcing a rewrite.
    
    ## Defaults worth keeping
    
    - local-first storage
    - allowlisted corpora
    - deny-by-default agent access
    - personal memory separate from workspace retrieval
    - minimal indexed file extensions
    - explicit exclude globs
    - incremental refresh before full rebuild
    - one stable wrapper for agent-facing search
    - validation before maturity claims
    
    ## When to read references
    
    - Read `references/privacy-and-boundaries.md` for safe corpus design and exclusions.
    - Read `references/agent-scoping.md` when mapping corpora and memory roots to agents.
    - Read `references/interface-contract.md` when building or reviewing the agent-facing search wrapper.
    - Read `references/maintenance-patterns.md` when adding status checks, selective refresh, and smoke tests.
    - Read `references/example-templates.md` when you need sanitized starter JSON examples.
    - Read `references/dependencies-and-platforms.md` when the user wants concrete runtime dependencies, embedding backend choices, or cross-platform guidance.
    - Read `references/preflight-and-install-policy.md` when deciding whether the skill is runnable now, blocked, or should first produce an installation task plan.
    - Read `references/quickstart-real-workspace.md` when the user wants to move from the demo path into a real workspace setup.
    - Read `references/runtime-layout.md` when the user wants a more runnable implementation footprint.
    - Read `references/design-rationale.md` when the user needs the architectural thesis, tradeoffs, or public-facing positioning.
    - Read `references/sanitized-demo.md` when the user wants a safe walkthrough or publishable example.
    - Read `references/validation-contract.md` when deciding what completion level has actually been achieved.
    - Read `references/minimal-e2e-demo.md` when the user wants a safe runnable proof path.
    - Read `references/anti-overclaim.md` before packaging or publicly promoting the skill.
    - Read `references/publish-readiness-checklist.md` before packaging or publicly promoting the skill.
    
    ## Output expectations
    
    When using this skill for a user request, produce some or all of the following depending on scope:
    - sanitized corpus config
    - agent allowlist config
    - memory-boundary config
    - search wrapper contract
    - maintenance workflow
    - smoke-test checklist
    - validation report with an honest maturity label
    - packaging-ready skill contents when the user wants distribution
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/ys-c-23-workspace-local-retrieval-skill-workspace-local-retrieval.md

// REPO STATS

0 stars
0 open issues
Last commit: 7mo ago