# Send Osori to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "osori",
    "name": "Osori",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/oozoofrog/osori",
    "canonicalUrl": "https://clawhub.ai/oozoofrog/osori",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/osori",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=osori",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "docs/examples/doctor-safe-fix.md",
      "docs/examples/multi-root-quickstart.md",
      "docs/multi-root-design.md",
      "docs/roadmap-v1.5.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/osori"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/osori",
    "downloadUrl": "https://openagent3.xyz/downloads/osori",
    "agentUrl": "https://openagent3.xyz/skills/osori/agent",
    "manifestUrl": "https://openagent3.xyz/skills/osori/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/osori/agent.md"
  }
}
```
## Documentation

### Osori (오소리)

Local project registry & context loader for AI agents.

### Prerequisites

macOS: mdfind (Spotlight, built-in), python3, git, gh CLI
Linux: mdfind unavailable → uses find as fallback automatically. python3, git, gh CLI required.
Entire integration (optional): entire CLI installed (for /entire-* commands)

### Dependencies

python3 — Required. Used for JSON processing.
git — Project detection and status checks.
entire — Optional. Required only for /entire-status, /entire-enable, /entire-rewind-list.

### Telegram Bot Commands (Updated in v1.6.1)

Osori now supports Telegram slash commands for quick project management:

/list [root] — Show registered projects (optional root filter)
/status [root] — Check status of projects (optional root filter)
/find <name> [root|--root <root>] — Find a project by name (optional root scope)
/switch <name> [root|--root <root>] [--index <n>] — Switch to project and load context (multi-match selection)
/fingerprints [name] [--root <root>] — Show repo remote + last commit + open PR/issue counts
/doctor [--fix] [--dry-run] [--yes] [--json] — Registry health check (preview-first, risk-gated)
/list-roots — List roots, labels, paths, and project counts
/root-add <key> [label] — Add root (or update label)
/root-path-add <key> <path> — Add discovery path to root
/root-path-remove <key> <path> — Remove discovery path from root
/root-set-label <key> <label> — Update root label
/root-remove <key> [--reassign <target>] [--force] — Safely remove root
/alias-add <alias> <project> — Add alias for project
/alias-remove <alias> — Remove alias
/favorites — Show favorite projects
/favorite-add <project> — Mark project as favorite
/favorite-remove <project> — Unmark favorite
/entire-status <project> [root|--root <root>] — Show Entire status in a project
/entire-enable <project> [root|--root <root>] [--agent <name>] [--strategy <name>] — Enable Entire in a project
/entire-rewind-list <project> [root|--root <root>] — List rewind points in a project
/add <path> — Add project to registry
/remove <name> — Remove project from registry
/scan <path> [root] — Scan directory for git projects, optional root key
/help — Show command help

### Setup

Add to your OpenClaw agent's TOOLS.md or Telegram bot config:

# In Telegram bot commands (BotFather)
list - Show all projects (or by root)
status - Check project statuses (or by root)
find - Find project by name
switch - Switch to project
fingerprints - Show repo/commit/PR/issue fingerprint
doctor - Health check (preview-first, risk-gated fix)
list-roots - Show roots and discovery paths
root-add - Add root
root-path-add - Add path to root
root-path-remove - Remove path from root
root-set-label - Rename root label
root-remove - Safely remove root (with reassign/force options)
alias-add - Add alias for a project
alias-remove - Remove alias
favorites - Show favorite projects
favorite-add - Mark favorite project
favorite-remove - Unmark favorite project
entire-status - Show Entire status for a project
entire-enable - Enable Entire for a project
entire-rewind-list - List rewind points for a project
add - Add project to registry
remove - Remove project
scan - Scan directory (optional root)
help - Show help

### Usage Examples

/list work
/status personal
/find agent-avengers work
/switch Tesella --root personal
/switch Tesella --root personal --index 1
/fingerprints Tesella --root personal
/doctor --fix
/list-roots
/root-add work Work
/root-path-add work /path/to/workspace
/root-remove work --reassign default
/alias-add rh RunnersHeart
/favorite-add RunnersHeart
/favorites
/entire-status osori
/entire-enable osori --agent claude-code --strategy manual-commit
/add /Volumes/disk/MyProject
/scan /path/to/workspace work

### Registry

${OSORI_REGISTRY:-$HOME/.openclaw/osori.json}

Override with the OSORI_REGISTRY environment variable.

### Versioning & Migration (v1.6.1)

Current schema: osori.registry
Current version: 2
On every load, Osori auto-migrates older registry formats:

legacy array ([]) → versioned object
object without schema/version → normalized versioned object


Normalized registry fields:

top-level roots[]
top-level aliases{} (alias → project name)
each projects[] item includes favorite: bool


Migration safety:

creates backup: osori.json.bak-<timestamp>
corrupted JSON is preserved as: osori.json.broken-<timestamp>
write path uses atomic replace + rollback fallback

### Finding Projects (when path is unknown)

When the project path is unknown, search in order:

Registry lookup — Fuzzy match name in osori.json
mdfind (macOS only) — mdfind "kMDItemFSName == '<name>'" | head -5
find fallback — Search priority:

roots[].paths from registry (if root is specified, that root first)
paths from OSORI_SEARCH_PATHS
Command form: find <search_paths> -maxdepth 4 -type d -name '<name>' 2>/dev/null


Ask the user — If all methods fail, ask for the project path directly.
Offer to register the found project in the registry.

### List

Show all registered projects. Optional root filter supported in Telegram command:

/list [root]

(Example: /list work)

### Switch

Supports optional root scope and explicit candidate selection:

/switch <name> [root|--root <root>] [--index <n>]

Flow:

Search registry (fuzzy match, root-scoped if provided)
If multiple matches:

show candidate list (name/root/path/last commit/dirty/score)
--index <n> to pick explicitly
no index => auto-pick highest score


If not found → run "Finding Projects" flow above and suggest add path
Load context:

git status --short
git branch --show-current
git log --oneline -5
gh issue list -R <repo> --limit 5 (when repo is set)


Present summary

Auto score policy:

+50 root exact (if root scope provided)
+30 name exact
+20 name prefix
+10 latest commit recency
-10 missing path
-5 repo missing
tie-break: latest commit, then name

### Fingerprints

Show a one-shot project fingerprint view:

repo remote URL
last commit hash/date
open PR count
open issue count

bash {baseDir}/scripts/project-fingerprints.sh [project-name]
bash {baseDir}/scripts/project-fingerprints.sh --root <root-key> [project-name]

GitHub open-count cache (PR/Issue):

default cache file: $HOME/.openclaw/osori-cache.json
default TTL: 600 seconds
env overrides:

OSORI_CACHE_FILE
OSORI_CACHE_TTL

### Add

bash {baseDir}/scripts/add-project.sh <path> [--tag <tag>] [--name <name>]

Auto-detects: git remote, language, description.

### Scan

bash {baseDir}/scripts/scan-projects.sh <root-dir> [--depth 3]
OSORI_ROOT_KEY=work bash {baseDir}/scripts/scan-projects.sh <root-dir> [--depth 3]

Bulk-scan a directory for git repos and add them to the registry.

Telegram command supports optional root key too:

/scan <path> [root]

### Remove

Delete an entry from osori.json by name.

### Status

Run git status + gh issue list for one or all projects.

Telegram root filter:

/status [root]

### Doctor

Registry health check with preview-first pipeline and risk-gated fixes.

Default (no flags): analyze + preview plan — no changes applied.

/doctor                     # preview only (default)
/doctor --fix               # preview + apply (high-risk blocked)
/doctor --fix --yes         # preview + apply all (including high-risk)
/doctor --dry-run           # explicit preview only (never applies)
/doctor --json              # machine-readable JSON output

Risk levels:

🟢 low — schema normalization, migration, missing fields
🟡 medium — duplicate removal, root reference repair
🔴 high — registry re-initialization from corrupted state

Shell equivalent:

bash {baseDir}/scripts/doctor.sh [--fix] [--dry-run] [--yes] [--json]

See also: Doctor Safe Fix Guide

### Root Management

/list-roots
/root-add <key> [label]
/root-path-add <key> <path>
/root-path-remove <key> <path>
/root-set-label <key> <label>
/root-remove <key> [--reassign <target>] [--force]

Shell equivalents:

bash {baseDir}/scripts/root-manager.sh list
bash {baseDir}/scripts/root-manager.sh add <key> [label]
bash {baseDir}/scripts/root-manager.sh path-add <key> <path>
bash {baseDir}/scripts/root-manager.sh path-remove <key> <path>
bash {baseDir}/scripts/root-manager.sh set-label <key> <label>
bash {baseDir}/scripts/root-manager.sh remove <key> [--reassign <target>] [--force]

Safety rules for remove:

default root cannot be removed
if projects exist in root:

--reassign <target> to move projects then remove
or --force to move projects to default and remove

### Alias & Favorites

/alias-add <alias> <project>
/alias-remove <alias>
/favorites
/favorite-add <project>
/favorite-remove <project>

Shell equivalents:

bash {baseDir}/scripts/alias-favorite-manager.sh alias-add <alias> <project>
bash {baseDir}/scripts/alias-favorite-manager.sh alias-remove <alias>
bash {baseDir}/scripts/alias-favorite-manager.sh aliases
bash {baseDir}/scripts/alias-favorite-manager.sh favorite-add <project>
bash {baseDir}/scripts/alias-favorite-manager.sh favorite-remove <project>
bash {baseDir}/scripts/alias-favorite-manager.sh favorites

Aliases are case-insensitive and are resolved by /find, /switch, and project-fingerprints.sh name queries.

### Entire Integration

Run Entire CLI commands in a registered project context:

/entire-status <project> [root|--root <root>]
/entire-enable <project> [root|--root <root>] [--agent <name>] [--strategy <name>]
/entire-rewind-list <project> [root|--root <root>]

Shell equivalent:

bash {baseDir}/scripts/entire-manager.sh status <project> [root|--root <root>]
bash {baseDir}/scripts/entire-manager.sh enable <project> [root|--root <root>] [entire enable flags...]
bash {baseDir}/scripts/entire-manager.sh rewind-list <project> [root|--root <root>]

Defaults:

entire enable defaults to --agent claude-code --strategy manual-commit when not provided.
/entire-rewind-list uses non-destructive JSON listing (entire rewind --list).

### Schema

{
  "schema": "osori.registry",
  "version": 2,
  "updatedAt": "2026-02-16T00:00:00Z",
  "roots": [
    {
      "key": "default",
      "label": "Default",
      "paths": []
    }
  ],
  "aliases": {
    "rh": "RunnersHeart"
  },
  "projects": [
    {
      "name": "string",
      "path": "/absolute/path",
      "repo": "owner/repo",
      "lang": "swift|typescript|python|rust|go|ruby|unknown",
      "tags": ["personal", "ios"],
      "description": "Short description",
      "addedAt": "YYYY-MM-DD",
      "root": "default",
      "favorite": false
    }
  ]
}

### Auto-trigger Rules

"work on X" / "X 프로젝트 작업하자" → switch X
"find project X" / "X 찾아줘" / "X 경로" → registry search or discover
"list projects" / "프로젝트 목록" → list
"add project" / "프로젝트 추가" → add
"project status" / "프로젝트 상태" → status all
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: oozoofrog
- Version: 1.6.1
## Source health
- Status: healthy
- Source download looks usable.
- Yavira can redirect you to the upstream package for this source.
- Health scope: source
- Reason: direct_download_ok
- Checked at: 2026-04-30T16:55:25.780Z
- Expires at: 2026-05-07T16:55:25.780Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/osori)
- [Send to Agent page](https://openagent3.xyz/skills/osori/agent)
- [JSON manifest](https://openagent3.xyz/skills/osori/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/osori/agent.md)
- [Download page](https://openagent3.xyz/downloads/osori)