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
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- clean-targetsSkill
- socai-releaseSkill
- socai-site-deploymentSkill
- rsiSkill
- socai-cliSkill
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
- Very specific: line 8
Use this skill when the task involves the selectable LLM model list for the socai desktop app or TUI.
- Distinctive: line 28
Prefer model sources in this order:
- Distinctive: line 30
Official provider APIs: when an API key is available and the endpoint returns relevant chat/agent models.
- Very specific: line 36
Do not blindly expose every pi model.
- Very specific: line 81
Use SOCAI_MODEL_SYNC_OFFLINE=1 or --no-official to avoid provider network calls.
- Distinctive: line 103
Run these from the repo root unless noted:
- Distinctive: line 136
Keep the JSON deterministic and sorted enough for review.
- Distinctive: line 139
Use real provider API model IDs, not display labels.
- Very specific: line 140
Do not add unsupported providers here without implementing their backend and credential handling in socai-core.
≈ “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.
Files
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.jsonRuntime readers:
core/src/agent/provider.rs— provider config, model catalog loading, persisted defaults.app/src-tauri/src/commands.rs—agent_list_modelsreturns 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—/modelpicker.
Prefer model sources in this order:
- Official provider APIs when an API key is available and the endpoint returns relevant chat/agent models.
- pi's generated catalog via
@earendil-works/pi-ai, when available. - 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:
anthropicopenaikimi/ Moonshotqwen/ DashScopedeepseek
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 --writeOfficial 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 --writeFrom the app package, the shortcut is:
pnpm --dir app sync-modelsFor a read-only freshness check:
node scripts/sync-model-catalog.mjs --checkUse 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/modelsProvider 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 buildFor 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')
PYExpected 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.provideranddefaults.{provider}_modelin~/.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.
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
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.

