soia-team/soia-open-skills / skills/soia-meta-sync-skills
soia-meta-sync-skills
Verified按明确范围把共享技能目录软链到项目或宿主,写入前先 dry-run。触发:技能同步、同步预览、把技能链到项目
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.1 KB |
| agents/openai.yaml | config | 262 B |
| assets/config.example.yml | config | 214 B |
| references/soia-managed-skills.md | markdown | 2.8 KB |
| references/source-rules.md | markdown | 2.0 KB |
| references/targets-and-confirmation.md | markdown | 3.6 KB |
| scripts/install_selection.py | script | 2.2 KB |
| scripts/sync_soia_skills.py | script | 34.7 KB |
scripts/sync_soia_skills.py
View on GitHub#!/usr/bin/env python3
"""Synchronize SOIA-managed skills as symlinks to selected agent directories."""
from __future__ import annotations
import argparse
import json
import os
import shutil
import sys
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
from install_selection import SCOPES, TARGET_KINDS, select as select_installation, tokens as selection_tokens
OPTIONAL_SKILLS: list[str] = []
RETIRED_SKILLS = [
"soia-dev-project-init",
"soia-gov-ui-validation",
"soia-gov-tauri-real-device-test", # merged into soia-gov-ui-design (2026-04-24)
"soia-brand-guidelines", # renamed to soia-design-brand-guidelines (2026-04-24)
"jiuan-docs-v5-project-structure",
"jiuan-docs-v5-references",
"soia-pkm-compose-article-draft",
"soia-pkm-cover-image",
"soia-pkm-publish-wechat-draft",
"soia-pkm-publish-x-thread",
"soia-pkm-publish-x-article",
"soia-pkm-publish-rednote-card",
"soia-dev-sync-skills",
"soia-dev-skill-release",
"soia-dev-prompt-clarity",
"soia-dev-ai-cli-upgrade",
"soia-dev-run-ops-inspection",
"soia-safe-audit-fix-codebase",
"soia-safe-track-vulnerability-intel",
# env skills removed 2026-11-11 (unused installers; no replacement skill)
"soia-env-antigravity-cli-install",
"soia-env-claude-cli-install",
"soia-env-deepcode-cli-install",
"soia-env-kimi-cli-install",
"soia-env-opencode-cli-install",
"soia-env-pi-cli-install",
"soia-env-qoder-cli-install",
"soia-env-codex-install",
"soia-env-codex-setup-support",
"soia-env-node-install",
"soia-env-python-install",
# env domain retired as a whole 2026-11-11 (no replacement skills)
"soia-env-ai-cli-upgrade",
"soia-env-environment-setup",
"soia-env-local-model-bench",
"soia-env-network-diagnose",
"soia-env-open-skills-install",
"soia-env-storage-cleanup",
"soia-env-workbuddy-install",
# dev skills removed 2026-11-11
"soia-dev-release-plan-checklist",
"soia-dev-test-draft-doc",
"soia-dev-archify-diagrams",
"soia-dev-drawio-visio-diagrams",
# merged 2026-11-11: agent-md-advisor -> soia-dev-project-scaffold (itself removed later the same day); publish-x-article/-thread -> soia-media-publish-x; feishu-doc-git-sync -> soia-cwork-feishu-cli
"soia-dev-agent-md-advisor",
"soia-media-publish-x-article",
"soia-media-publish-x-thread",
"soia-cwork-feishu-doc-git-sync",
# dev skills removed 2026-11-11 (second batch; project-scaffold included, so its merged advisor entry is gone too)
"soia-dev-open-design-ops",
"soia-dev-doc-sync",
"soia-dev-draft-feature-spec",
"soia-dev-officecli-ops",
"soia-dev-terminal-ops",
"soia-dev-project-scaffold",
# pkm skills removed 2026-11-11 (no usage trace)
"soia-pkm-bootstrap-vault-ima",
"soia-pkm-transform-obsidian-pdf",
"soia-pkm-transform-article-ppt",
"soia-pkm-reading-plan",
# edu repository retired 2026-11-11 (no replacement)
"soia-edu-design-course-outline",
"soia-edu-compose-lesson-plan",
# meta skill removed 2026-11-11
"soia-meta-publish-market",
# corp skills removed 2026-11-11 (soia-corp-upgrade-framework-major stays)
"soia-corp-ba-draft-requirement",
"soia-corp-release-plan-checklist",
"soia-corp-safe-audit-codebase",
"soia-corp-safe-vuln-intel",
"soia-corp-test-draft-test-doc",
"soia-corp-ts-inspect-data",
"soia-corp-ts-inspect-env",
"soia-corp-ts-inspect-system",
# soia-private-skills repository retired and deleted 2026-11-11 (gov / workspace / harness roots)
"soia-gov-coding-protocol",
"soia-gov-disaster-recovery",
"soia-gov-doc-sync",
"soia-gov-fix-loop",
"soia-gov-git-workflow",
"soia-gov-project-scaffold",
"soia-gov-proposal-flow",
"soia-gov-release",
"soia-gov-session-history",
"soia-gov-session-startup",
"soia-gov-task-execute",
"soia-gov-ui-design",
"soia-design-brand-guidelines",
"soia-design-stitch",
"soia-dev-code-review",
"soia-dev-coding-agent",
"soia-dev-task-prompt",
"soia-meta-harness",
]
@dataclass(frozen=True)
class Target:
id: str
label: str
path: Path
@dataclass
class SyncConfig:
source_dir: str | None
targets: list[str]
excludes: dict[str, list[str]]
TARGETS = {
"pi": Target("pi", "Pi (pi-coding-agent)", Path("~/.pi/agent/skills")),
"soia": Target("soia", "SOIA AI", Path("~/.soia/skills")),
"workbuddy": Target("workbuddy", "WorkBuddy", Path("~/.workbuddy/skills")),
"claude": Target("claude", "Claude Code", Path("~/.claude/skills")),
"codex": Target("codex", "OpenAI Codex", Path("~/.codex/skills")),
"agy": Target("agy", "Antigravity CLI", Path("~/.gemini/antigravity-cli/skills")),
"gemini": Target("gemini", "Gemini CLI (non-consumer lanes)", Path("~/.gemini/skills")),
"kimi": Target("kimi", "Kimi CLI", Path("~/.kimi/skills")),
"opencode": Target("opencode", "OpenCode", Path("~/.config/opencode/skill")),
"qwen": Target("qwen", "Qwen Code", Path("~/.qwen/skills")),
"cursor": Target("cursor", "Cursor", Path("~/.cursor/skills")),
"qoder": Target("qoder", "QoderCLI", Path("~/.qoder/skills")),
"copilot": Target("copilot", "GitHub Copilot", Path("~/.copilot/skills")),
"windsurf": Target("windsurf", "Windsurf", Path("~/.codeium/windsurf/skills")),
"trae": Target("trae", "Trae", Path("~/.trae/skills")),
"openclaw": Target("openclaw", "OpenClaw", Path("~/.openclaw/skills")),
}
DEFAULT_ORDER = [
"pi",
"claude",
"qoder",
"copilot",
"cursor",
"agy",
"gemini",
"kimi",
"codex",
"opencode",
"windsurf",
"trae",
"qwen",
"openclaw",
]
def expanded(path: Path) -> Path:
return path.expanduser()
def display_path(path: Path) -> str:
resolved = path.expanduser()
home = Path.home()
try:
rel = resolved.relative_to(home)
except ValueError:
return str(resolved)
if str(rel) == ".":
return "~"
return f"~/{rel.as_posix()}"
def default_source_dir() -> Path:
return Path(__file__).resolve().parents[2]
def default_config_file() -> Path:
override = os.environ.get("SOIA_META_SYNC_SKILLS_CONFIG_FILE")
if override:
return Path(override).expanduser()
if os.name == "nt" and os.environ.get("APPDATA"):
base = Path(os.environ["APPDATA"])
else:
base = Path.home() / ".config"
return base / "soia-skills" / "soia-meta-sync-skills" / "config.yml"
def clean_config_scalar(value: str) -> str:
value = value.strip()
if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
if value[0] == '"':
try:
parsed = json.loads(value)
except json.JSONDecodeError:
return value[1:-1]
return parsed if isinstance(parsed, str) else value[1:-1]
return value[1:-1].replace("''", "'")
return value
def parse_inline_config_list(value: str) -> list[str]:
value = value.strip()
if not value:
return []
if not (value.startswith("[") and value.endswith("]")):
raise ValueError(f"expected an inline YAML list, got: {value}")
inner = value[1:-1].strip()
if not inner:
return []
return [clean_config_scalar(item) for item in inner.split(",") if item.strip()]
def split_config_mapping(value: str) -> tuple[str, str] | None:
quote: str | None = None
escaped = False
for index, char in enumerate(value):
if escaped:
escaped = False
continue
if quote == '"' and char == "\\":
escaped = True
continue
if char in {"'", '"'}:
if quote == char:
quote = None
elif quote is None:
quote = char
continue
if char == ":" and quote is None:
return value[:index], value[index + 1:]
return None
def load_config(path: Path) -> SyncConfig:
if not path.is_file():
return SyncConfig(None, [], {})
try:
lines = path.read_text(encoding="utf-8").splitlines()
except (OSError, UnicodeError) as exc:
raise ValueError(f"cannot read config file {display_path(path)}: {exc}") from exc
source_dir: str | None = None
targets: list[str] = []
excludes: dict[str, list[str]] = {}
section: str | None = None
exclude_target: str | None = None
for line_no, raw in enumerate(lines, start=1):
if not raw.strip() or raw.lstrip().startswith("#"):
continue
indent = len(raw) - len(raw.lstrip(" "))
stripped = raw.strip()
if indent == 0:
section = None
exclude_target = None
mapping = split_config_mapping(stripped)
if mapping is None:
raise ValueError(f"invalid config line {line_no}: expected key: value")
key, value = mapping
key = key.strip()
value = value.strip()
if key == "source_dir":
source_dir = clean_config_scalar(value) or None
elif key in {"targets", "excludes"}:
section = key
if value and value != "{}":
raise ValueError(f"invalid config line {line_no}: {key} must be a YAML block")
continue
if section == "targets" and stripped.startswith("- "):
target = clean_config_scalar(stripped[2:])
if target:
targets.append(target)
continue
if section == "excludes":
mapping = split_config_mapping(stripped)
if indent == 2 and mapping is not None:
raw_target, value = mapping
exclude_target = clean_config_scalar(raw_target)
if not exclude_target:
raise ValueError(f"invalid config line {line_no}: empty exclude target")
excludes[exclude_target] = parse_inline_config_list(value)
continue
if indent >= 4 and stripped.startswith("- ") and exclude_target:
skill = clean_config_scalar(stripped[2:])
if skill:
excludes[exclude_target].append(skill)
continue
raise ValueError(f"invalid config line {line_no}: unsupported YAML shape")
for target, names in excludes.items():
invalid = [name for name in names if not is_managed_soia_skill(name)]
if invalid:
raise ValueError(
f"config excludes for {target} contain non-SOIA names: {', '.join(invalid)}"
)
excludes[target] = list(dict.fromkeys(names))
return SyncConfig(source_dir, list(dict.fromkeys(targets)), excludes)
def save_config(path: Path, config: SyncConfig) -> None:
lines = ["# User-owned defaults. CLI arguments take precedence.", "schema_version: 3"]
if config.source_dir:
lines.append(f"source_dir: {json.dumps(config.source_dir, ensure_ascii=False)}")
if config.targets:
lines.append("targets:")
lines.extend(f" - {json.dumps(target, ensure_ascii=False)}" for target in config.targets)
lines.append("excludes:")
if config.excludes:
for target in sorted(config.excludes):
lines.append(f" {json.dumps(target, ensure_ascii=False)}:")
lines.extend(
f" - {json.dumps(skill, ensure_ascii=False)}"
for skill in sorted(set(config.excludes[target]))
)
else:
lines[-1] = "excludes: {}"
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
# Audit log: this sync tool creates/replaces symlinks and removes retired or
# dangling managed entries, i.e. real system-state changes, so a trace belongs in XDG state
# (not TMPDIR, which is for disposable run reports) — see SKILL_SPEC.md "Script
# Disk-Write Destinations" category B.
AUDIT_LOG_RETENTION = 20
def audit_log_dir() -> Path:
base = os.environ.get("XDG_STATE_HOME") or "~/.local/state"
return Path(base).expanduser() / "soia-meta-sync-skills"
def rotate_audit_logs(log_dir: Path, keep: int) -> None:
"""Keep at most `keep` existing sync-*.log files, deleting the oldest first."""
if not log_dir.is_dir():
return
logs = sorted(log_dir.glob("sync-*.log")) # timestamped names sort chronologically
excess = len(logs) - keep
if excess <= 0:
return
for stale in logs[:excess]:
try:
stale.unlink()
except OSError:
pass
def parse_target_tokens(values: list[str] | None) -> list[str]:
if not values:
return []
tokens: list[str] = []
for raw in values:
tokens.extend(token.strip() for token in raw.split(",") if token.strip())
return tokens
def target_from_token(token: str) -> Target:
if token in TARGETS:
target = TARGETS[token]
return Target(target.id, target.label, expanded(target.path))
path = expanded(Path(token))
if path.is_absolute() or token.startswith((".", "~")):
return Target("custom", "Custom path", path)
raise ValueError(f"unknown target id or path: {token}")
def default_targets() -> list[Target]:
targets: list[Target] = []
for target_id in DEFAULT_ORDER:
target = target_from_token(target_id)
if target.path.exists() or (target.id == "agy" and shutil.which("agy") is not None):
targets.append(target)
return targets
def selected_targets(tokens: list[str]) -> list[Target]:
if not tokens:
return []
if tokens == ["*"]:
targets = [target_from_token(target_id) for target_id in TARGETS]
else:
targets = [target_from_token(token) for token in tokens]
deduped: list[Target] = []
seen: set[Path] = set()
for target in targets:
resolved = target.path.resolve(strict=False)
if resolved in seen:
continue
seen.add(resolved)
deduped.append(target)
return deduped
def target_config_key(target: Target) -> str:
target_path = target.path.resolve(strict=False)
for target_id, known in TARGETS.items():
if expanded(known.path).resolve(strict=False) == target_path:
return target_id
return display_path(target.path)
def ensure_not_source_target(source_dir: Path, targets: list[Target]) -> None:
source_resolved = source_dir.resolve(strict=False)
for target in targets:
if target.path.resolve(strict=False) == source_resolved:
raise ValueError(f"target must not equal source-dir: {display_path(target.path)}")
def has_skill_md(path: Path) -> bool:
return path.is_dir() and (path / "SKILL.md").is_file()
def is_managed_soia_skill(name: str) -> bool:
"""Treat every installed `soia-*` skill as managed.
The shared source may contain skills published from more than one repository.
Repository ownership controls publishing, while this script controls target links; excluding public PKM names here made a full
sync silently incomplete and broke explicit --skills requests.
"""
return name.startswith("soia-")
def discover_skills(source_dir: Path, include_optional: bool) -> list[str]:
skills: list[str] = []
for child in sorted(source_dir.iterdir(), key=lambda item: item.name):
name = child.name
if not has_skill_md(child):
continue
if name in OPTIONAL_SKILLS:
if include_optional:
skills.append(name)
continue
if is_managed_soia_skill(name):
skills.append(name)
return skills
def select_skills(discovered: list[str], requested: list[str]) -> list[str]:
if not requested:
return discovered
available = set(discovered)
missing = [name for name in requested if name not in available]
if missing:
raise ValueError(f"requested skills not found in source-dir: {', '.join(missing)}")
return list(dict.fromkeys(requested))
def parse_hard_deps(skill_dir: Path) -> list[str]:
"""Read `dependencies.hard` from a skill's SKILL.md frontmatter (stdlib only).
Supported forms inside the frontmatter block:
dependencies:
hard: [a, b]
and
dependencies:
hard:
- a
- b
Everything else in `dependencies` (optional/external) is ignored here:
optional deps are runtime-reminder territory, not install-closure input.
"""
skill_md = skill_dir / "SKILL.md"
if not skill_md.is_file():
return []
try:
lines = skill_md.read_text(encoding="utf-8").splitlines()
except OSError:
return []
if not lines or lines[0].strip() != "---":
return []
def clean(token: str) -> str:
return token.strip().strip("'\"")
deps: list[str] = []
in_dependencies = False
in_hard_list = False
for line in lines[1:]:
if line.strip() == "---":
break
indent = len(line) - len(line.lstrip(" "))
stripped = line.strip()
if not stripped or stripped.startswith("#"):
continue
if indent == 0:
in_dependencies = stripped == "dependencies:"
in_hard_list = False
continue
if not in_dependencies:
continue
if in_hard_list:
if stripped.startswith("- "):
name = clean(stripped[2:])
if name:
deps.append(name)
continue
in_hard_list = False # dedent or sibling key ends the block list
if stripped.startswith("hard:"):
value = stripped[len("hard:"):].strip()
if value.startswith("[") and value.endswith("]"):
deps.extend(
name for name in (clean(t) for t in value[1:-1].split(",")) if name
)
elif not value:
in_hard_list = True
return list(dict.fromkeys(deps))
def expand_with_hard_deps(
selected: list[str], source_dir: Path, discovered: list[str]
) -> tuple[list[str], dict[str, str], list[tuple[str, str]]]:
"""Expand a skill selection with its transitive hard-dependency closure.
Returns (expanded selection, {added_dep: first_requirer}, [(missing_dep, requirer)]).
Deps absent from the source-dir are reported, not linked: they usually live
in the sibling repo and need `npx skills add` first.
"""
available = set(discovered)
expanded = list(selected)
seen = set(selected)
added: dict[str, str] = {}
missing: list[tuple[str, str]] = []
queue = list(selected)
while queue:
current = queue.pop(0)
for dep in parse_hard_deps(source_dir / current):
if dep in seen:
continue
seen.add(dep)
if dep in available:
expanded.append(dep)
added[dep] = current
queue.append(dep)
else:
missing.append((dep, current))
return expanded, added, missing
def existing_path(path: Path) -> bool:
return path.exists() or path.is_symlink()
def remove_path(path: Path, dry_run: bool) -> bool:
if not existing_path(path):
return False
if not dry_run:
if path.is_symlink() or path.is_file():
path.unlink()
else:
shutil.rmtree(path)
return True
def symlink_target(source: Path, dest: Path) -> Path:
target = os.path.relpath(source.resolve(strict=False), dest.parent.resolve(strict=False))
return Path(target)
def link_skill(source: Path, dest: Path, dry_run: bool) -> Path:
target = symlink_target(source, dest)
if not dry_run:
dest.symlink_to(target, target_is_directory=True)
return target
def prune_dangling_soia_symlinks(
target_dir: Path, dry_run: bool, planned_names: set[str]
) -> list[Path]:
"""Remove first-level dangling symlinks not already repaired by this sync."""
if not target_dir.is_dir():
return []
pruned: list[Path] = []
for entry in sorted(target_dir.iterdir(), key=lambda item: item.name):
if entry.name in planned_names or not entry.name.startswith("soia-"):
continue
if not entry.is_symlink() or entry.exists():
continue
if not dry_run:
entry.unlink()
pruned.append(entry)
return pruned
def sync(
source_dir: Path,
targets: list[Target],
skills: list[str],
dry_run: bool,
cleanup_retired: bool = True,
prune: bool = True,
excludes_by_target: dict[str, set[str]] | None = None,
) -> int:
linked = 0
cleaned = 0
overwritten = 0
created_targets = 0
excluded_unlinked = 0
excludes_by_target = excludes_by_target or {}
# Audit log setup happens before any stdout output; log content is additive
# and never changes what already gets printed below.
log_dir = audit_log_dir()
rotate_audit_logs(log_dir, keep=AUDIT_LOG_RETENTION - 1)
audit_lines: list[str] = [
f"run_time: {datetime.now().isoformat(timespec='seconds')}",
f"mode: {'dry-run' if dry_run else 'write'}",
f"source_dir: {source_dir}",
]
print(f"Mode: {'DRY-RUN' if dry_run else 'WRITE'}")
print(f"Source: {display_path(source_dir)}")
retired_count = len(RETIRED_SKILLS) if cleanup_retired else 0
print(f"Skills: {len(skills)} selected, {retired_count} retired cleanup names")
print("Install mode: symlink")
print(f"Targets: {len(targets)}")
for target in targets:
print(f"\n[{target.id}] {target.label}: {display_path(target.path)}")
audit_lines.append(f"target {target.id}: {target.path}")
target_excludes = excludes_by_target.get(target_config_key(target), set())
target_skills = [skill for skill in skills if skill not in target_excludes]
if target_excludes:
print(f" excludes: {', '.join(sorted(target_excludes))}")
audit_lines.append(f" excludes: {', '.join(sorted(target_excludes))}")
if not target.path.exists():
created_targets += 1
print(" create target directory")
if not dry_run:
target.path.mkdir(parents=True, exist_ok=True)
audit_lines.append(f" created target directory: {target.path}")
if cleanup_retired:
for retired in RETIRED_SKILLS:
retired_path = target.path / retired
if remove_path(retired_path, dry_run):
cleaned += 1
print(f" remove retired: {retired}")
audit_lines.append(f" removed retired entry: {retired_path}")
for skill in sorted(target_excludes):
excluded_path = target.path / skill
if excluded_path.is_symlink():
if not dry_run:
excluded_path.unlink()
excluded_unlinked += 1
print(f" unlink excluded: {skill}")
audit_lines.append(f" unlinked excluded symlink: {excluded_path}")
elif existing_path(excluded_path):
print(f" keep excluded non-symlink: {skill}")
audit_lines.append(f" kept excluded non-symlink: {excluded_path}")
for skill in target_skills:
source = source_dir / skill
dest = target.path / skill
replaced = remove_path(dest, dry_run)
if replaced:
overwritten += 1
action = "relink"
else:
action = "link"
target_path = link_skill(source, dest, dry_run)
print(f" {action}: {skill} -> {target_path}")
audit_lines.append(
f" {'replaced' if replaced else 'created'} symlink: {dest} -> {target_path}"
)
linked += 1
if prune:
planned_names = set(target_skills) | target_excludes
if cleanup_retired:
planned_names.update(RETIRED_SKILLS)
for dangling_path in prune_dangling_soia_symlinks(
target.path, dry_run, planned_names
):
cleaned += 1
print(f" prune dangling symlink: {dangling_path.name}")
audit_lines.append(f" unlinked dangling symlink: {dangling_path}")
print("\nSummary:")
print(f"- target dirs created: {created_targets}")
print(f"- retired dirs cleaned: {cleaned}")
print(f"- overwritten skill entries: {overwritten}")
print(f"- symlinked skill entries: {linked}")
print(f"- excluded symlinks removed: {excluded_unlinked}")
print("- unrelated target entries: untouched")
audit_lines.append(
"summary: "
f"target_dirs_created={created_targets} "
f"retired_dirs_cleaned={cleaned} "
f"overwritten_skill_entries={overwritten} "
f"symlinked_skill_entries={linked} "
f"excluded_symlinks_removed={excluded_unlinked}"
)
if dry_run:
return 0
log_dir.mkdir(parents=True, exist_ok=True)
# Microseconds prevent a dry-run followed immediately by write mode from
# silently overwriting the first audit record in the same second.
log_path = log_dir / f"sync-{datetime.now().strftime('%Y-%m-%d_%H-%M-%S-%f')}.log"
log_path.write_text("\n".join(audit_lines) + "\n", encoding="utf-8")
return 0
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description=(
"Symlink SOIA skills to selected targets, clean retired names, and prune dangling "
"soia-* symlinks."
)
)
parser.add_argument(
"--source-dir",
help=(
"Directory containing SOIA skill folders. CLI overrides config; otherwise defaults "
"to the installed shared skill directory inferred from this script."
),
)
parser.add_argument(
"--targets",
action="append",
help="Comma-separated global target ids or custom paths; '*' requires --dry-run then --confirm-all-targets.",
)
parser.add_argument(
"--skills",
action="append",
help="Comma-separated managed skill names; '*' requires --target-kind all.",
)
parser.add_argument("--scope", choices=SCOPES, help="Required install scope: project or global.")
parser.add_argument("--project-dir", type=Path, help="Required with --scope project; only <project>/.agents/skills is written.")
parser.add_argument("--agents", action="append", help="Repeatable customer-selected agents; project scope records intent but does not map host paths.")
parser.add_argument("--target-kind", choices=TARGET_KINDS, help="Required selection granularity: skill, domain, or all.")
parser.add_argument("--domain", action="append", help="Repeatable SOIA domain name used with --target-kind domain.")
parser.add_argument("--confirm-all-targets", action="store_true", help="Acknowledge a reviewed all-target dry-run before a '*' write.")
parser.add_argument("--legacy-default-all", action="store_true", help="Deprecated: preserve pre-scope default global full sync for old automation.")
parser.add_argument(
"--exclude-skills",
action="append",
help=(
"Comma-separated soia-* skill names to skip and unlink for every selected target "
"in this run."
),
)
parser.add_argument(
"--save-excludes",
action="store_true",
help="Merge --exclude-skills into the private config for each selected target.",
)
parser.add_argument(
"--config-file",
type=Path,
help="Private config path; overrides SOIA_META_SYNC_SKILLS_CONFIG_FILE and the default.",
)
parser.add_argument(
"--optional",
action="store_true",
help="Include optional non-SOIA skills. No optional entries are currently bundled.",
)
parser.add_argument(
"--no-deps",
action="store_true",
help="Skip hard-dependency closure when --skills is given; sync exactly the named skills.",
)
parser.add_argument(
"--no-prune",
action="store_true",
help="Keep dangling soia-* symlinks in target directories instead of pruning them.",
)
parser.add_argument(
"--dry-run",
action="store_true",
help="Print planned creates, removes, and symlinks without writing.",
)
parser.add_argument(
"--list-targets",
action="store_true",
help="List supported target ids and paths, then exit.",
)
parser.add_argument(
"--list-skills",
action="store_true",
help="List discovered managed skills from source-dir, then exit.",
)
return parser
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
config_path = (args.config_file or default_config_file()).expanduser()
try:
config = load_config(config_path)
except ValueError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
if args.list_targets:
for target_id in DEFAULT_ORDER:
target = target_from_token(target_id)
exists = "exists" if target.path.exists() else "missing"
print(f"{target.id:10} {display_path(target.path):34} {exists} {target.label}")
return 0
source_value = args.source_dir or config.source_dir or str(default_source_dir())
source_dir = expanded(Path(source_value))
if not source_dir.is_dir():
print(f"error: source-dir is not a directory: {source_dir}", file=sys.stderr)
return 2
discovered_skills = discover_skills(source_dir, args.optional)
if args.list_skills:
for skill in discovered_skills:
print(skill)
return 0
requested_skill_tokens = parse_target_tokens(args.skills)
cli_excludes = parse_target_tokens(args.exclude_skills)
invalid_excludes = [name for name in cli_excludes if not is_managed_soia_skill(name)]
if invalid_excludes:
print(
f"error: --exclude-skills accepts only soia-* names: {', '.join(invalid_excludes)}",
file=sys.stderr,
)
return 2
if args.save_excludes and not cli_excludes:
print("error: --save-excludes requires --exclude-skills", file=sys.stderr)
return 2
if args.save_excludes and args.dry_run:
print("error: --save-excludes cannot be combined with --dry-run", file=sys.stderr)
return 2
scope = args.scope
target_kind = args.target_kind
if args.legacy_default_all:
print("warning: --legacy-default-all is deprecated; pass --scope global --target-kind all explicitly", file=sys.stderr)
scope = scope or "global"
target_kind = target_kind or ("skill" if requested_skill_tokens else "all")
try:
selection = select_installation(
scope=scope,
agents=args.agents,
target_kind=target_kind,
requested_skills=args.skills,
requested_domains=args.domain,
discovered=discovered_skills,
)
except ValueError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
if selection.selection_required:
print(json.dumps({"selection_required": True, "pending": list(selection.pending), "scope": scope, "target_kind": target_kind}, ensure_ascii=False))
return 0
skills = list(selection.skills)
if not skills:
print(f"error: no SOIA skills found in source-dir: {source_dir}", file=sys.stderr)
return 2
# Hard-dependency closure: single-skill sync pulls in declared hard deps so a
# customer never gets a skill without the skills it cannot run without.
if requested_skill_tokens and not args.no_deps:
skills, added_deps, missing_deps = expand_with_hard_deps(
skills, source_dir, discovered_skills
)
for dep, requirer in added_deps.items():
print(f"note: auto-including hard dependency: {dep} (required by {requirer})")
else:
# Full sync links everything discovered anyway; still surface cross-repo
# gaps where a skill declares a hard dep the shared source doesn't have.
_, _, missing_deps = expand_with_hard_deps(skills, source_dir, discovered_skills)
for dep, requirer in missing_deps:
print(
f"warning: hard dependency not in source-dir: {dep} (required by {requirer}). "
"Use soia-meta-find-skill and the installation owner to choose project/global scope, "
"explicit agents, and a narrow target before re-running this sync.",
file=sys.stderr,
)
cli_target_tokens = parse_target_tokens(args.targets)
if scope == "global" and not cli_target_tokens and not args.legacy_default_all:
print(json.dumps({"selection_required": True, "pending": ["targets"], "scope": scope, "target_kind": target_kind}, ensure_ascii=False))
return 0
if scope == "project":
if not args.project_dir:
print(json.dumps({"selection_required": True, "pending": ["project_dir"], "scope": scope, "target_kind": target_kind}, ensure_ascii=False))
return 0
project = args.project_dir.expanduser().resolve()
if not project.is_dir() or project in {Path.home().resolve(), Path(project.anchor)} or project == source_dir.resolve():
print("error: --project-dir must be an existing, non-home, non-root project distinct from source-dir", file=sys.stderr)
return 2
targets = [Target("project", "Project .agents skills", project / ".agents" / "skills")]
else:
tokens = cli_target_tokens or config.targets
try:
targets = default_targets() if args.legacy_default_all and not tokens else selected_targets(tokens)
except ValueError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
if target_kind == "all" and not args.dry_run and not args.confirm_all_targets:
print("error: --target-kind all requires a reviewed --dry-run and --confirm-all-targets before writing", file=sys.stderr)
return 2
try:
ensure_not_source_target(source_dir, targets)
except ValueError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
excludes_by_target: dict[str, set[str]] = {}
for target in targets:
key = target_config_key(target)
persistent = set(config.excludes.get(key, []))
excludes_by_target[key] = persistent | set(cli_excludes)
if args.save_excludes:
for target in targets:
key = target_config_key(target)
config.excludes[key] = sorted(excludes_by_target[key])
try:
save_config(config_path, config)
except OSError as exc:
print(f"error: cannot save config file {display_path(config_path)}: {exc}", file=sys.stderr)
return 2
print(f"saved excludes: {display_path(config_path)}")
return sync(
source_dir,
targets,
skills,
args.dry_run,
cleanup_retired=not bool(requested_skill_tokens),
prune=not args.no_prune,
excludes_by_target=excludes_by_target,
)
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |