Add global scope, config CLI, and Win locks

Introduce a structured config command namespace with tools and
default-tool management while keeping `agr tools` as a deprecated
alias. Add `--global/-g` support for add/remove/list/sync so users
can manage skills in `~/.agr/agr.toml` and tool global directories
outside git repositories.

Extend fetcher/install helpers to support explicit skills directories
for global installs and store global local dependencies as absolute
paths for stable sync/remove behavior. Replace SDK cache file locking
with a cross-platform backend that uses `msvcrt` on Windows and
`fcntl` on POSIX.

Update docs and changelog and add coverage for config commands,
global flag flows, and cache lock backends.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: kasperjunge

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+### Added
+- `agr config` command group with `tools` and `default-tool` subcommands
+- Global scope flags (`-g`, `--global`) for `agr add`, `agr remove`, `agr sync`, and `agr list`
+- Global config helpers for `~/.agr/agr.toml`
+- Cross-platform cache lock backends in SDK cache (`msvcrt` on Windows, `fcntl` on POSIX)
+- CLI tests for `agr config` commands and global flag flows
+- SDK cache tests for Windows and POSIX lock wrappers
+
+### Changed
+- `agr tools` now behaves as a deprecated alias of `agr config tools` with a warning
+- Fetch/install helpers now support global installs via explicit skills directory overrides
+- README and reference docs now document `agr config` and global install/list/sync/remove commands
+- Docs tests now validate `agr config` command documentation
+
+### Fixed
+- Global local dependencies are stored as absolute paths so `sync -g` and `remove -g` work reliably across directories
+- SDK cache no longer hard-depends on Unix-only `fcntl` lock calls
+
 ## [0.7.4] - 2026-02-06
 ### Added
 - Antigravity tool support with workspace `.agent/skills/` and global `~/.gemini/antigravity/skills/` paths

README.md

@@ -52,6 +52,7 @@ That's it. The skill is now available in your configured tool (Claude Code, Code
 
 ```bash
 agr add anthropics/skills/frontend-design     # Install a skill
+agr add -g anthropics/skills/frontend-design  # Install globally for your user
 agr add anthropics/skills/pdf anthropics/skills/mcp-builder   # Install multiple
 agr add anthropics/skills/pdf --source github # Install from an explicit source
 ```
@@ -173,11 +174,17 @@ agr init --migrate
 | Command | Description |
 |---------|-------------|
 | `agr add <handle>` | Install a skill |
+| `agr add -g <handle>` | Install a skill globally |
 | `agr remove <handle>` | Uninstall a skill |
+| `agr remove -g <handle>` | Uninstall a global skill |
 | `agr sync` | Install all from agr.toml |
+| `agr sync -g` | Sync global dependencies |
 | `agr list` | Show installed skills |
+| `agr list -g` | Show global skills |
 | `agr init` | Create agr.toml |
 | `agr init <name>` | Create a new skill |
+| `agr config tools ...` | Manage configured tools |
+| `agr config default-tool ...` | Manage agrx default tool |
 | `agrx <handle>` | Run skill temporarily |
 
 ---

agr/commands/add.py

@@ -2,7 +2,15 @@
 
 from rich.console import Console
 
-from agr.config import AgrConfig, Dependency, find_config, find_repo_root
+from pathlib import Path
+
+from agr.config import (
+    AgrConfig,
+    Dependency,
+    find_config,
+    find_repo_root,
+    get_or_create_global_config,
+)
 from agr.exceptions import AgrError, InvalidHandleError
 from agr.fetcher import fetch_and_install_to_tools
 from agr.handle import parse_handle
@@ -11,31 +19,41 @@
 
 
 def run_add(
-    refs: list[str], overwrite: bool = False, source: str | None = None
+    refs: list[str],
+    overwrite: bool = False,
+    source: str | None = None,
+    global_install: bool = False,
 ) -> None:
     """Run the add command.
 
     Args:
         refs: List of handles or paths to add
         overwrite: Whether to overwrite existing skills
     """
-    # Find repo root
-    repo_root = find_repo_root()
-    if repo_root is None:
-        console.print("[red]Error:[/red] Not in a git repository")
-        raise SystemExit(1)
-
-    # Find or create config
-    config_path = find_config()
-    if config_path is None:
-        config_path = repo_root / "agr.toml"
-        config = AgrConfig()
+    skills_dirs: dict[str, Path] | None = None
+    if global_install:
+        repo_root = None
+        config_path, config = get_or_create_global_config()
     else:
-        config = AgrConfig.load(config_path)
+        # Find repo root
+        repo_root = find_repo_root()
+        if repo_root is None:
+            console.print("[red]Error:[/red] Not in a git repository")
+            raise SystemExit(1)
+
+        # Find or create config
+        config_path = find_config()
+        if config_path is None:
+            config_path = repo_root / "agr.toml"
+            config = AgrConfig()
+        else:
+            config = AgrConfig.load(config_path)
 
     # Get configured tools
     tools = config.get_tools()
     resolver = config.get_source_resolver()
+    if global_install:
+        skills_dirs = {tool.name: tool.get_global_skills_dir() for tool in tools}
 
     # Track results for summary
     results: list[tuple[str, bool, str]] = []  # (ref, success, message)
@@ -60,17 +78,24 @@ def run_add(
                 overwrite,
                 resolver=resolver,
                 source=source,
+                skills_dirs=skills_dirs,
             )
             installed_paths = [
                 f"{name}: {path}" for name, path in installed_paths_dict.items()
             ]
 
             # Add to config
             if handle.is_local:
+                path_value = ref
+                if global_install and handle.local_path is not None:
+                    if handle.local_path.is_absolute():
+                        path_value = str(handle.local_path.resolve())
+                    else:
+                        path_value = str((Path.cwd() / handle.local_path).resolve())
                 config.add_dependency(
                     Dependency(
                         type="skill",
-                        path=ref,
+                        path=path_value,
                     )
                 )
             else:

agr/commands/list.py

@@ -5,7 +5,7 @@
 from rich.console import Console
 from rich.table import Table
 
-from agr.config import AgrConfig, find_config, find_repo_root
+from agr.config import AgrConfig, find_config, find_repo_root, get_global_config_path
 from agr.fetcher import is_skill_installed
 from agr.handle import ParsedHandle, parse_handle
 from agr.tool import ToolConfig
@@ -15,9 +15,10 @@
 
 def _get_installation_status(
     handle: ParsedHandle,
-    repo_root: Path,
+    repo_root: Path | None,
     tools: list[ToolConfig],
     source: str | None = None,
+    skills_dirs: dict[str, Path] | None = None,
 ) -> str:
     """Get installation status across all configured tools.
 
@@ -32,7 +33,13 @@ def _get_installation_status(
     installed_tools = [
         tool.name
         for tool in tools
-        if is_skill_installed(handle, repo_root, tool, source)
+        if is_skill_installed(
+            handle,
+            repo_root,
+            tool,
+            source,
+            skills_dir=skills_dirs.get(tool.name) if skills_dirs is not None else None,
+        )
     ]
 
     if len(installed_tools) == len(tools):
@@ -43,26 +50,37 @@ def _get_installation_status(
         return "[yellow]not synced[/yellow]"
 
 
-def run_list() -> None:
+def run_list(global_install: bool = False) -> None:
     """Run the list command.
 
     Lists all dependencies from agr.toml with their sync status.
     """
-    # Find repo root
-    repo_root = find_repo_root()
-    if repo_root is None:
-        console.print("[red]Error:[/red] Not in a git repository")
-        raise SystemExit(1)
-
-    # Find config
-    config_path = find_config()
-    if config_path is None:
-        console.print("[yellow]No agr.toml found.[/yellow]")
-        console.print("[dim]Run 'agr init' to create one.[/dim]")
-        return
+    skills_dirs: dict[str, Path] | None = None
+    if global_install:
+        repo_root = None
+        config_path = get_global_config_path()
+        if not config_path.exists():
+            console.print("[yellow]No global agr.toml found.[/yellow]")
+            console.print("[dim]Run 'agr add -g <handle>' to create one.[/dim]")
+            return
+    else:
+        # Find repo root
+        repo_root = find_repo_root()
+        if repo_root is None:
+            console.print("[red]Error:[/red] Not in a git repository")
+            raise SystemExit(1)
+
+        # Find config
+        config_path = find_config()
+        if config_path is None:
+            console.print("[yellow]No agr.toml found.[/yellow]")
+            console.print("[dim]Run 'agr init' to create one.[/dim]")
+            return
 
     config = AgrConfig.load(config_path)
     tools = config.get_tools()
+    if global_install:
+        skills_dirs = {tool.name: tool.get_global_skills_dir() for tool in tools}
 
     if not config.dependencies:
         console.print("[yellow]No dependencies in agr.toml.[/yellow]")
@@ -96,7 +114,9 @@ def run_list() -> None:
             source_name = (
                 None if dep.is_local else (dep.source or config.default_source)
             )
-            status = _get_installation_status(handle, repo_root, tools, source_name)
+            status = _get_installation_status(
+                handle, repo_root, tools, source_name, skills_dirs
+            )
         except Exception:
             status = "[red]invalid[/red]"
 

agr/commands/remove.py

@@ -1,36 +1,54 @@
 """agr remove command implementation."""
 
+from pathlib import Path
+
 from rich.console import Console
 
-from agr.config import AgrConfig, find_config, find_repo_root
+from agr.config import (
+    AgrConfig,
+    find_config,
+    find_repo_root,
+    get_global_config_path,
+)
 from agr.fetcher import uninstall_skill
 from agr.handle import parse_handle
 
 console = Console()
 
 
-def run_remove(refs: list[str]) -> None:
+def run_remove(refs: list[str], global_install: bool = False) -> None:
     """Run the remove command.
 
     Args:
         refs: List of handles or paths to remove
     """
-    # Find repo root
-    repo_root = find_repo_root()
-    if repo_root is None:
-        console.print("[red]Error:[/red] Not in a git repository")
-        raise SystemExit(1)
-
-    # Find config
-    config_path = find_config()
-    if config_path is None:
-        console.print("[red]Error:[/red] No agr.toml found")
-        raise SystemExit(1)
+    skills_dirs: dict[str, Path] | None = None
+    if global_install:
+        repo_root = None
+        config_path = get_global_config_path()
+        if not config_path.exists():
+            console.print("[red]Error:[/red] No global agr.toml found")
+            console.print("[dim]Run 'agr add -g <handle>' first.[/dim]")
+            raise SystemExit(1)
+    else:
+        # Find repo root
+        repo_root = find_repo_root()
+        if repo_root is None:
+            console.print("[red]Error:[/red] Not in a git repository")
+            raise SystemExit(1)
+
+        # Find config
+        config_path = find_config()
+        if config_path is None:
+            console.print("[red]Error:[/red] No agr.toml found")
+            raise SystemExit(1)
 
     config = AgrConfig.load(config_path)
 
     # Get configured tools
     tools = config.get_tools()
+    if global_install:
+        skills_dirs = {tool.name: tool.get_global_skills_dir() for tool in tools}
 
     # Track results
     results: list[tuple[str, bool, str]] = []
@@ -43,6 +61,18 @@ def run_remove(refs: list[str]) -> None:
             dep = config.get_by_identifier(ref)
             if dep is None and handle.is_local:
                 dep = config.get_by_identifier(str(handle.local_path))
+            if (
+                dep is None
+                and global_install
+                and handle.is_local
+                and handle.local_path is not None
+            ):
+                absolute_path = (
+                    handle.local_path.resolve()
+                    if handle.local_path.is_absolute()
+                    else (Path.cwd() / handle.local_path).resolve()
+                )
+                dep = config.get_by_identifier(str(absolute_path))
             if dep is None and not handle.is_local:
                 dep = config.get_by_identifier(handle.to_toml_handle())
 
@@ -53,7 +83,16 @@ def run_remove(refs: list[str]) -> None:
             # Remove from filesystem for all configured tools
             removed_fs = False
             for tool in tools:
-                if uninstall_skill(handle, repo_root, tool, source_name):
+                target_skills_dir = (
+                    skills_dirs.get(tool.name) if skills_dirs is not None else None
+                )
+                if uninstall_skill(
+                    handle,
+                    repo_root,
+                    tool,
+                    source_name,
+                    skills_dir=target_skills_dir,
+                ):
                     removed_fs = True
 
             # Remove from config
@@ -62,6 +101,18 @@ def run_remove(refs: list[str]) -> None:
             if not removed_config and handle.is_local:
                 # Try with the path
                 removed_config = config.remove_dependency(str(handle.local_path))
+            if (
+                not removed_config
+                and global_install
+                and handle.is_local
+                and handle.local_path is not None
+            ):
+                absolute_path = (
+                    handle.local_path.resolve()
+                    if handle.local_path.is_absolute()
+                    else (Path.cwd() / handle.local_path).resolve()
+                )
+                removed_config = config.remove_dependency(str(absolute_path))
             if not removed_config:
                 # Try with toml handle
                 removed_config = config.remove_dependency(handle.to_toml_handle())