agentleFS
socai-iosocai-io/socai/.claude/skills/socai-model-sync/SKILL.md

socai-model-sync

Skill257 starsChanged 50 days agoApache-2.0View on GitHub

Refresh, inspect, and validate socai's generated desktop/CLI LLM model catalog. Use when adding or updating model versions such as Qwen 3.6/3.7, aligning with pi's model list, checking official provider model APIs, or troubleshooting the desktop model picker.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this skill when the task involves the selectable LLM model list for the socai desktop app or TUI.

    line 8
  2. Distinctive:

    Prefer model sources in this order:

    line 28
  3. Distinctive:

    Official provider APIs: when an API key is available and the endpoint returns relevant chat/agent models.

    line 30
  4. Very specific:

    Do not blindly expose every pi model.

    line 36
  5. Very specific:

    Use SOCAI_MODEL_SYNC_OFFLINE=1 or --no-official to avoid provider network calls.

    line 81
  6. Distinctive:

    Run these from the repo root unless noted:

    line 103
  7. Distinctive:

    Keep the JSON deterministic and sorted enough for review.

    line 136
  8. Distinctive:

    Use real provider API model IDs, not display labels.

    line 139
  9. Very specific:

    Do not add unsupported providers here without implementing their backend and credential handling in socai-core.

    line 140

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

socai model sync

Use this skill when the task involves the selectable LLM model list for the socai desktop app or TUI. The shipped app must not depend on runtime model network calls; model discovery is a maintainer/developer-time operation that updates a generated catalog committed to the repo.

Source of truth and priorities

Generated file:

core/src/agent/model_catalog.generated.json

Runtime readers:

  • core/src/agent/provider.rs — provider config, model catalog loading, persisted defaults.
  • app/src-tauri/src/commands.rs — agent_list_models returns model-version rows to the desktop UI.
  • app/src/panels/tasks.ts / app/src/panels/task_new.ts — desktop model picker and task summary.
  • cli/src/tui.rs — /model picker.

Prefer model sources in this order:

  1. Official provider APIs when an API key is available and the endpoint returns relevant chat/agent models.
  2. pi's generated catalog via @earendil-works/pi-ai, when available.
  3. socai fallback entries in scripts/sync-model-catalog.mjs, for defaults and providers whose APIs/catalogs do not map cleanly.

Do not blindly expose every pi model. socai currently implements only:

  • anthropic
  • openai
  • kimi / Moonshot
  • qwen / DashScope
  • deepseek

Qwen/DashScope deserves extra judgment: pi often lists Qwen through OpenRouter, Together, Fireworks, or opencode providers. Normalize only model IDs that are valid for DashScope-compatible calls, such as qwen3.8-max, qwen3.8-flash, qwen3.7-plus, and qwen3.7-max. If uncertain, keep the known fallback and note the uncertainty.

Refresh commands

Offline/pi-aligned refresh, deterministic when no official keys are desired:

node scripts/sync-model-catalog.mjs --no-official --write

Official API refresh. Set any available keys; missing providers fall back to pi or local fallback entries:

ANTHROPIC_API_KEY=... \
OPENAI_API_KEY=... \
KIMI_API_KEY=... \
QWEN_API_KEY=... \
DEEPSEEK_API_KEY=... \
node scripts/sync-model-catalog.mjs --write

From the app package, the shortcut is:

pnpm --dir app sync-models

For a read-only freshness check:

node scripts/sync-model-catalog.mjs --check

Use SOCAI_MODEL_SYNC_OFFLINE=1 or --no-official to avoid provider network calls. Use --no-pi to test the built-in fallback path.

Official endpoint notes

The sync script knows these endpoints:

Anthropic: GET https://api.anthropic.com/v1/models
OpenAI:    GET https://api.openai.com/v1/models
Kimi:      GET https://api.moonshot.cn/v1/models
Qwen:      GET https://dashscope.aliyuncs.com/compatible-mode/v1/models
DeepSeek:  GET https://api.deepseek.com/v1/models

Provider model APIs frequently include non-agent models. Filter out embeddings, image/audio/realtime/moderation models, and anything that socai's current LLM backends cannot call. If an official API returns a suspicious list, prefer a smaller safe catalog over showing broken options.

Validation after a refresh

Run these from the repo root unless noted:

cargo test
pnpm --dir app build

For quick UI-level sanity, inspect the generated catalog and ensure every provider still has its compiled default model visible:

python3 - <<'PY'
import json
from pathlib import Path
catalog = json.loads(Path('core/src/agent/model_catalog.generated.json').read_text())
for provider, models in catalog['providers'].items():
    print(provider, len(models), models[0]['id'] if models else 'EMPTY')
PY

Expected UI behavior:

  • The desktop model menu groups rows by provider.
  • Each row shows only the human display name.
  • API-key entry remains provider-level, not model-level.
  • Selecting a model persists defaults.provider and defaults.{provider}_model in ~/.socai/auth.json.
  • Starting an agent task sends the concrete model id to the Rust backend.

When editing manually

Manual edits are allowed for urgent fallbacks, but keep them conservative:

  • Keep the JSON deterministic and sorted enough for review.
  • Preserve the provider's compiled default model in its list.
  • Mark exactly one practical default per provider with "recommended": true.
  • Use real provider API model IDs, not display labels.
  • Do not add unsupported providers here without implementing their backend and credential handling in socai-core.

Reporting back

Include:

  • Which sources were used: official API, pi catalog, fallback.
  • Providers/model counts changed.
  • Notable additions/removals, especially Qwen/ChatGPT/Anthropic versions.
  • Validation commands run and their results.
  • Any uncertainty about official availability or provider compatibility.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.