"""Per-agent skill destinations (Claude, Cursor, Windsurf, AGENTS.md, Gemini)."""
from __future__ import annotations
import os
from collections.abc import Callable
from pathlib import Path
from .constants import SKILL_NAME
from .skill import (
BLOCK_BEGIN,
BLOCK_END,
fetch_skill,
split_skill,
upsert_block,
write_file,
)
[docs]
def shared_skill(root: Path, content: str, force: bool) -> tuple[str, Path]:
"""Write the full skill to ``.agents/skills`` for pointer blocks to refer to.
Args:
root (Path): Project directory.
content (str): Full SKILL.md text.
force (bool): Overwrite a differing existing file.
Returns:
tuple[str, Path]: Write status and the skill file path.
Raises:
OSError: If the file cannot be written.
"""
dst = root / ".agents" / "skills" / SKILL_NAME / "SKILL.md"
return write_file(dst, content, force), dst
[docs]
def pointer_block(skill_path: Path, root: Path, description: str) -> str:
"""Build the short marked block that points an agent at the skill file.
Args:
skill_path (Path): Location of the full skill; must be inside ``root``.
root (Path): Project directory the path is made relative to.
description (str): One-line skill description shown in the block.
Returns:
str: Markdown block including the ``BEGIN``/``END`` markers.
Raises:
ValueError: If ``skill_path`` is not inside ``root``.
"""
rel = skill_path.relative_to(root).as_posix()
return "\n".join(
[
BLOCK_BEGIN,
"",
"## Google Scholar search",
"",
description,
"",
f"Read `{rel}` before using the Google Scholar MCP tools.",
"",
BLOCK_END,
]
)
def _t_claude(base: Path) -> Callable[..., tuple[str, Path]]:
"""Create an installer that writes ``<base>/skills/<name>/SKILL.md``.
Args:
base (Path): Claude config directory (``~/.claude`` or ``.claude``).
Returns:
Callable[..., tuple[str, Path]]: Installer taking ``(root, content, force)``.
"""
def install(root: Path, content: str, force: bool) -> tuple[str, Path]:
"""Install the skill for one agent.
Args:
root (Path): Project directory.
content (str): Full SKILL.md text.
force (bool): Overwrite a differing existing file.
Returns:
tuple[str, Path]: Status (``installed``, ``current`` or
``skipped``) and the file written or checked.
Raises:
OSError: If the file cannot be written.
"""
dst = base / "skills" / SKILL_NAME / "SKILL.md"
return write_file(dst, content, force), dst
return install
def _project_claude(root: Path, content: str, force: bool) -> tuple[str, Path]:
"""Install the skill into the project's ``.claude`` directory.
Args:
root (Path): Project directory.
content (str): Full SKILL.md text.
force (bool): Overwrite a differing existing file.
Returns:
tuple[str, Path]: Status and the file written or checked.
Raises:
OSError: If the file cannot be written.
"""
return _t_claude(root / ".claude")(root, content, force)
def _t_rules(
rel_dir: str, suffix: str, frontmatter: str
) -> Callable[..., tuple[str, Path]]:
"""Create an installer that writes the skill as an editor rule file.
Args:
rel_dir (str): Rules directory relative to the project root.
suffix (str): File extension including the dot.
frontmatter (str): Template with a ``{description}`` placeholder.
Returns:
Callable[..., tuple[str, Path]]: Installer taking ``(root, content, force)``.
"""
def install(root: Path, content: str, force: bool) -> tuple[str, Path]:
"""Install the skill for one agent.
Args:
root (Path): Project directory.
content (str): Full SKILL.md text.
force (bool): Overwrite a differing existing file.
Returns:
tuple[str, Path]: Status (``installed``, ``current`` or
``skipped``) and the file written or checked.
Raises:
OSError: If the file cannot be written.
"""
desc, body = split_skill(content)
dst = root / rel_dir / f"{SKILL_NAME}{suffix}"
text = frontmatter.format(description=desc) + "\n" + body
return write_file(dst, text, force), dst
return install
def _t_instructions(filename: str) -> Callable[..., tuple[str, Path]]:
"""Create an installer that adds a pointer block to an instructions file.
Args:
filename (str): Shared file at the project root, e.g. ``AGENTS.md``.
Returns:
Callable[..., tuple[str, Path]]: Installer taking ``(root, content, force)``.
"""
def install(root: Path, content: str, force: bool) -> tuple[str, Path]:
"""Install the skill for one agent.
Args:
root (Path): Project directory.
content (str): Full SKILL.md text.
force (bool): Overwrite a differing existing file.
Returns:
tuple[str, Path]: Status (``installed``, ``current`` or
``skipped``) and the file written or checked.
Raises:
OSError: If the file cannot be written.
"""
status, skill = shared_skill(root, content, force)
if status == "skipped":
return status, skill
desc, _ = split_skill(content)
path = root / filename
block_status = upsert_block(path, pointer_block(skill, root, desc), force)
if block_status == "skipped":
return "skipped", path
merged = "installed" if "installed" in (status, block_status) else "current"
return merged, path
return install
# name -> (label, detect(root), install(root, content, force) -> (status, path))
TARGETS: dict[
str, tuple[str, Callable[[Path], bool], Callable[..., tuple[str, Path]]]
] = {
"claude-user": (
"Claude Code (user)",
lambda root: True, # default destination, as before
_t_claude(Path.home() / ".claude"),
),
"claude": (
"Claude Code (project)",
lambda root: (root / ".claude").is_dir(),
_project_claude,
),
"cursor": (
"Cursor",
lambda root: (root / ".cursor").is_dir(),
_t_rules(
".cursor/rules",
".mdc",
"---\ndescription: {description}\nalwaysApply: false\n---\n",
),
),
"windsurf": (
"Windsurf",
lambda root: (root / ".windsurf").is_dir(),
_t_rules(
".windsurf/rules",
".md",
"---\ntrigger: model_decision\ndescription: {description}\n---\n",
),
),
"agents": (
"AGENTS.md (Codex, Amp, OpenCode, Jules, ...)",
lambda root: (root / "AGENTS.md").is_file(),
_t_instructions("AGENTS.md"),
),
"gemini": (
"Gemini CLI",
lambda root: (root / "GEMINI.md").is_file() or (root / ".gemini").is_dir(),
_t_instructions("GEMINI.md"),
),
}
[docs]
def detect_targets(root: Path) -> list[str]:
"""List the agents that appear to be used in a project.
Args:
root (Path): Project directory to inspect.
Returns:
list[str]: Names from ``TARGETS`` whose marker file or directory exists
(``claude-user`` is always included).
"""
return [name for name, (_, detect, _i) in TARGETS.items() if detect(root)]
[docs]
def install_skill(
targets: list[str] | None = None, root: Path | None = None, force: bool = False
) -> list[tuple[str, str, Path | None]]:
"""Install the skill into several agents.
Never overwrites a differing file unless ``force`` is set. Per-target
write errors are printed and reported as ``"error"`` instead of raised.
Args:
targets (list[str] | None): Names from ``TARGETS``; ``None`` means
every detected agent.
root (Path | None): Project directory (default: current directory).
force (bool): Overwrite differing files.
Returns:
list[tuple[str, str, Path | None]]: ``(target, status, path)`` per
target, status being ``installed``, ``current``, ``skipped`` or
``error`` (path is ``None`` on error).
Raises:
KeyError: If a name in ``targets`` is not in ``TARGETS``.
"""
from ..config import DEFAULT_SKILL_URL
root = root or Path.cwd()
chosen = targets or detect_targets(root)
content, source = fetch_skill(os.getenv("GS_SKILL_URL", DEFAULT_SKILL_URL))
results: list[tuple[str, str, Path | None]] = []
for name in chosen:
label, _detect, install = TARGETS[name]
try:
status, path = install(root, content, force)
except OSError as exc:
print(f" x {label}: {exc}")
results.append((name, "error", None))
continue
marker = {"installed": "+", "current": "=", "skipped": "!"}[status]
extra = (
" (differs; re-run with --force to overwrite)"
if status == "skipped"
else ""
)
src = f" from {source}" if status == "installed" else ""
print(f" {marker} {label}{src}: {path}{extra}")
results.append((name, status, path))
return results