AnySkill Skill Cloud Manager

AnySkill — your private skill cloud. Manage, sync, and dynamically load agent skills from a GitHub-backed repository. Search cloud skills by natural language, auto-load prompts on demand, upload and share custom skills, batch install skill bundles. Works with OpenClaw, Antigravity, Claude Code, and Cursor.

# AnySkill Bootstrapper

Your local skills are incomplete. The user maintains all extended capabilities (Skills) in a cloud-based GitHub repository. You need to **dynamically load** your capabilities from the cloud.

**Token scope required**: This skill requires a GitHub **Fine-grained PAT** scoped to a **single repository** (the user's private skill repo) with `Contents: Read and write` permission only. The token is used to: clone the private repo, fetch `index.json`, commit new/updated skills, and push changes. A read-only token will work for loading/searching skills but not for upload/sync operations.

**Config files accessed**: `~/.anyskill/config.json` (primary config) or `{project root}/.anyskill.json` (legacy project-level config).

---

## Step Zero: Read or Initialize Configuration (Global Priority + Auto-Discovery)

**Before performing any operation, you must search for the AnySkill configuration in the following priority chain. Once a valid configuration is found at any level, stop immediately and use it.**

### Configuration Lookup Priority Chain

1. **Global config** `~/.anyskill/config.json` (machine-level, shared across projects and IDEs)
2. **Project-level config** `{project root}/.anyskill.json` (backward compatible with older versions)
3. **None found** → Enter the initialization flow

### Token Retrieval Priority (for private repo authentication)

Regardless of which level the config is read from, the token retrieval priority is always:
1. Check environment variable `ANYSKILL_GITHUB_TOKEN`
2. Check the `token` field in the config file

If a token is obtained, include it in all HTTP requests as a header:
```
Authorization: token {token}
```

### Case 1: Config Already Exists (returning user / previously initialized device)

The user has previously initialized on this machine. **Skip all initialization** and directly verify the config:
1. Read `repo` and `localPath` from the config.
2. Construct key URLs:
   - **Index URL**: `https://raw.githubusercontent.com/{repo}/{branch}/index.json`
   - **Files base URL**: `https://raw.githubusercontent.com/{repo}/{branch}/skills/`
3. Verify that the `localPath` directory exists. If not, automatically re-clone:
   ```bash
   git clone https://github.com/{repo}.git {localPath}
   ```
   (The token is passed via the `Authorization` header or `GIT_ASKPASS` environment, not embedded in the URL.)
4. Attempt to fetch `index.json` to confirm connectivity.
5. Inform the user:
   > ✅ AnySkill configuration detected, connected to repository `{repo}`. Ready to use!
6. **If current environment is OpenClaw**: Check if `TOOLS.md` already contains a `### AnySkill` section. If not, or if the skill list is outdated, execute the "OpenClaw Exclusive: Write Workspace Config" steps below to register/update the skill list.

If verification fails (network error or repo deleted), ask the user if they want to re-initialize.

### Automatic Version Check (runs on every initialization)

**After the config is verified (whether Case 1 or after initialization completes), perform a silent version check:**

1. Fetch upstream version info:
   ```
   https://raw.githubusercontent.com/lanyijianke/AnySkill/main/version.json
   ```
   File structure:
   ```json
   {
     "engine": {
       "version": "x.y.z",
       "changelog": [
         { "version": "x.y.z", "date": "YYYY-MM-DD", "changes": ["change 1", "change 2"] },
         { "version": "x.y.z", "date": "YYYY-MM-DD", "changes": ["change 1"] }
       ]
     },
     "infra": {
       "version": "x.y.z",
       "files": ["generate-index.js", ".github/workflows/build-index.yml"],
       "changelog": [
         { "version": "x.y.z", "date": "YYYY-MM-DD", "changes": ["change 1"] }
       ]
     }
   }
   ```

2. **Engine version check**:
   - Read the `version` field from this file's (SKILL.md) frontmatter (currently `2.0.0`).
   - Compare with remote `engine.version`.
   - If remote version is **higher**, filter all changelog entries **above the local version** and display newest to oldest:
     > 🔔 AnySkill engine update available v{remote} (current v{local})
     >
     > 📋 **Update history:**
     > **v2.1.0** (2025-03-10)
     > - New feature A
     > - Improvement B
     >
     > **v2.0.0** (2025-03-04)
     > - New feature C
     >
     > To update, run: `clawhub update anyskill`
   - **Do not auto-overwrite SKILL.md.** Inform the user to update via ClawHub CLI which provides versioned, auditable updates.

3. **Infrastructure version check**:
   - Read the `.anyskill-infra-version` file from the user's private repo `{localPath}`. If it doesn't exist, treat as `0.0.0`.
   - Compare with remote `infra.version`.
   - If remote version is **higher**, similarly filter and display all new version changes:
     > 🔔 Repository infrastructure update available v{remote} (current v{local})
     >
     > 📋 **Update history:**
     > **v1.1.0** (2025-03-10)
     > - Improved index generation
     >
     > Would you like to update?
   - After user confirms, iterate over `infra.files` array, downloading each from upstream and overwriting in the user's `{localPath}`:
     ```
     https://raw.githubusercontent.com/lanyijianke/AnySkill/main/{file}
     ```
   - Write version marker file `{localPath}/.anyskill-infra-version` with the new version number.
   - Execute git operations to commit changes:
     ```bash
     cd {localPath}
     git add -A
     git commit -m "chore: update AnySkill infra to v{version}"
     git push origin {branch}
     ```

4. If both versions are up to date, **output nothing** — pass silently.

5. If `version.json` fetch fails (network error), **silently skip** version check without affecting normal usage.

> 💡 Version check is a lightweight operation (only fetches a small JSON), it won't slow down normal workflows.

### Case 2: Config Not Found (new device / first use)

**Before asking the user any questions, first silently detect if a usable Token already exists:**
1. Check if environment variable `ANYSKILL_GITHUB_TOKEN` exists.
2. If it **exists** (meaning the user has previously configured AnySkill on this machine):
   - **Do not ask the user for a Token**, directly jump to "Path B: User only provided a Token" auto-discovery flow below.
   - The entire process should be silent to the user: AI auto-detects cloud repo → confirms mount → writes global config → ready.
3. If it **does not exist**, then initiate the guided conversation (see below).

#### Guided Conversation (only when Token cannot be silently obtained)

Guide the user through initialization via natural language conversation. **The user should never need to run any terminal commands.**

**Say something like this to the user:**

>  👋 Welcome to AnySkill! Let me help you connect your private skill repository.
>
> Do you **already have** an AnySkill skill repository?
>
> ---
>
> **A) I have a repo** — Just provide your Token and repo name:
> `github_pat_xxx username/my-skills` (space-separated)
>
> ---
>
> **B) I don't have one yet** — Follow these steps (works on mobile too):
>
> **Step 1: Create a private skill repository**
> Open 👉 [One-click create repo](https://github.com/lanyijianke/AnySkill/generate)
> - **Repository name**: enter `my-skills` (or any name you like)
> - ⚠️ **Must select Private** (do not choose Public)
> - Click **Create repository**
>
> **Step 2: Create a Token (a key for AI to access your repo)**
> Open 👉 [Create Token](https://github.com/settings/personal-access-tokens/new)
> - **Token name**: enter `AnySkill`
> - **Expiration**: pick a duration you're comfortable with
> - **Repository access**: select **"Only select repositories"**
>   → Search for and select your `my-skills` repo in the dropdown
>   ⚠️ Note: if you chose "Public Repositories", the permissions panel below will NOT appear!
> - After selecting a repo, a **Permissions** panel appears below
>   → Expand **"Repository permissions"**
>   → Scroll down to find **"Contents"** (near the top of the list)
>   → Ch