gl-cursor-skill 0.1.0__py3-none-any.whl

gl_cursor_skill/__init__.py

@@ -0,0 +1,3 @@
+"""Tools for installing local AI-agent skills."""
+
+__version__ = "0.1.0"

gl_cursor_skill/agents.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AgentProfile:
+    key: str
+    label: str
+    global_dir: Path
+    project_dir: Path
+    aliases: tuple[str, ...] = ()
+
+
+def home() -> Path:
+    return Path.home()
+
+
+AGENTS: tuple[AgentProfile, ...] = (
+    AgentProfile(
+        key="codex",
+        label="Codex",
+        global_dir=home() / ".codex" / "skills",
+        project_dir=Path(".codex") / "skills",
+    ),
+    AgentProfile(
+        key="claude-code",
+        label="Claude Code",
+        global_dir=home() / ".claude" / "skills",
+        project_dir=Path(".claude") / "skills",
+        aliases=("claude", "claudecode", "claude_code"),
+    ),
+    AgentProfile(
+        key="cursor",
+        label="Cursor",
+        global_dir=home() / ".cursor" / "skills",
+        project_dir=Path(".cursor") / "skills",
+    ),
+)
+
+
+def normalize_agent(value: str) -> AgentProfile:
+    wanted = value.strip().lower().replace(" ", "-")
+    for agent in AGENTS:
+        names = (agent.key, *agent.aliases)
+        if wanted in names:
+            return agent
+    valid = ", ".join(agent.key for agent in AGENTS)
+    raise ValueError(f"Unknown agent '{value}'. Expected one of: {valid}")
+
+
+def agent_choices() -> list[tuple[str, str]]:
+    return [(agent.label, agent.key) for agent in AGENTS]

gl_cursor_skill/cli.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+from typing import Optional
+
+import questionary
+from rich.console import Console
+from rich.table import Table
+import typer
+
+from . import __version__
+from .agents import AGENTS, agent_choices, normalize_agent
+from .core import (
+    SkillCandidate,
+    SkillError,
+    build_install_plan,
+    install_skill,
+    known_source_dirs,
+    normalize_scope,
+    resolve_source_candidates,
+)
+
+
+app = typer.Typer(
+    add_completion=False,
+    help="Install AI-agent skills between Claude, Codex, Cursor, and project scopes.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"gl-cursor-skill {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def callback(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show the installed gl-cursor-skill version.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    pass
+
+
+@app.command()
+def agents() -> None:
+    """Show known agent skill directories."""
+    table = Table(title="Known agent skill directories")
+    table.add_column("Agent")
+    table.add_column("Global")
+    table.add_column("Project")
+
+    for agent in AGENTS:
+        table.add_row(agent.label, str(agent.global_dir), str(agent.project_dir))
+
+    console.print(table)
+
+
+@app.command(name="list")
+def list_skills(
+    project_dir: Optional[Path] = typer.Option(
+        None,
+        "--project-dir",
+        "-p",
+        help="Project root used when listing project skill folders.",
+    ),
+) -> None:
+    """List discovered local skills."""
+    table = Table(title="Discovered skills")
+    table.add_column("Source")
+    table.add_column("Skill")
+    table.add_column("Path")
+
+    found_any = False
+    for base in known_source_dirs(project_dir):
+        if not base.path.is_dir():
+            continue
+        for child in sorted(base.path.iterdir(), key=lambda item: item.name.lower()):
+            if child.is_dir() and (child / "SKILL.md").is_file():
+                found_any = True
+                table.add_row(base.label, child.name, str(child))
+
+    if found_any:
+        console.print(table)
+    else:
+        console.print("[yellow]No skills found in known directories.[/yellow]")
+
+
+@app.command()
+def add(
+    skill: Optional[str] = typer.Argument(
+        None,
+        help="Skill name or path to a skill directory containing SKILL.md.",
+    ),
+    agent: Optional[str] = typer.Option(
+        None,
+        "--agent",
+        "-a",
+        help="Target agent: codex, cursor, or claude-code.",
+    ),
+    scope: Optional[str] = typer.Option(
+        None,
+        "--scope",
+        "-s",
+        help="Install scope: global or project.",
+    ),
+    source: Optional[str] = typer.Option(
+        None,
+        "--from",
+        "-f",
+        help="Source agent or path. Examples: claude, codex, cursor, /path/to/skill.",
+    ),
+    project_dir: Optional[Path] = typer.Option(
+        None,
+        "--project-dir",
+        "-p",
+        help="Project root used for project scope and project-source discovery.",
+    ),
+    dest: Optional[Path] = typer.Option(
+        None,
+        "--dest",
+        help="Override the destination skills directory.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Overwrite the target skill if it already exists.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the planned install without copying files.",
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Do not prompt; use defaults where possible.",
+    ),
+) -> None:
+    """Install a skill into an agent's global or project skill directory."""
+    interactive = _can_prompt(yes)
+    project_root = project_dir.expanduser() if project_dir is not None else Path.cwd()
+
+    try:
+        skill_name = _resolve_skill_arg(skill, interactive)
+        target_agent = normalize_agent(agent) if agent else _choose_agent(interactive, yes)
+        target_scope = normalize_scope(scope) if scope else _choose_scope(interactive, yes)
+        source_dir = _choose_source(skill_name, source, project_root, interactive, yes)
+        plan = build_install_plan(source_dir, target_agent, target_scope, project_root, dest)
+        _print_plan(plan, dry_run, force)
+        install_skill(plan, force=force, dry_run=dry_run)
+    except (SkillError, ValueError) as error:
+        console.print(f"[red]Error:[/red] {error}")
+        raise typer.Exit(code=1) from error
+
+    if dry_run:
+        console.print("[cyan]Dry run complete. No files were changed.[/cyan]")
+    else:
+        console.print(f"[green]Installed[/green] {plan.skill_name} -> {plan.target_dir}")
+        console.print("Restart the target agent if it does not pick up new skills automatically.")
+
+
+def _can_prompt(yes: bool) -> bool:
+    return not yes and sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _resolve_skill_arg(skill: Optional[str], interactive: bool) -> str:
+    if skill:
+        return skill
+    if not interactive:
+        raise SkillError("Skill is required in non-interactive mode.")
+    answer = questionary.text("Skill name or path:").ask()
+    if not answer:
+        raise SkillError("Skill is required.")
+    return answer
+
+
+def _choose_agent(interactive: bool, yes: bool):
+    if yes:
+        return normalize_agent("codex")
+    if not interactive:
+        raise SkillError("Missing --agent in non-interactive mode.")
+
+    choices = [questionary.Choice(title=label, value=value) for label, value in agent_choices()]
+    answer = questionary.select("Install for which agent?", choices=choices).ask()
+    if not answer:
+        raise SkillError("Target agent is required.")
+    return normalize_agent(answer)
+
+
+def _choose_scope(interactive: bool, yes: bool) -> str:
+    if yes:
+        return "global"
+    if not interactive:
+        raise SkillError("Missing --scope in non-interactive mode.")
+
+    answer = questionary.select(
+        "Install scope?",
+        choices=[
+            questionary.Choice(title="Global", value="global"),
+            questionary.Choice(title="Project", value="project"),
+        ],
+    ).ask()
+    if not answer:
+        raise SkillError("Scope is required.")
+    return normalize_scope(answer)
+
+
+def _choose_source(
+    skill: str,
+    source: Optional[str],
+    project_root: Path,
+    interactive: bool,
+    yes: bool,
+) -> Path:
+    candidates = resolve_source_candidates(skill, source, project_root)
+    if not candidates:
+        hint = f" from '{source}'" if source else ""
+        raise SkillError(f"Could not find skill '{skill}'{hint}.")
+
+    if len(candidates) == 1:
+        return candidates[0].path
+
+    if yes:
+        return candidates[0].path
+
+    if not interactive:
+        lines = "\n".join(f"- {candidate.label}: {candidate.path}" for candidate in candidates)
+        raise SkillError(f"Multiple source skills found; pass --from or run interactively.\n{lines}")
+
+    choices = [
+        questionary.Choice(title=f"{candidate.label}: {candidate.path}", value=str(index))
+        for index, candidate in enumerate(candidates)
+    ]
+    answer = questionary.select("Install from which source?", choices=choices).ask()
+    if answer is None:
+        raise SkillError("Source selection is required.")
+    return candidates[int(answer)].path
+
+
+def _print_plan(plan, dry_run: bool, force: bool) -> None:
+    table = Table(title="Install plan")
+    table.add_column("Field")
+    table.add_column("Value")
+    table.add_row("Skill", plan.skill_name)
+    table.add_row("Target agent", plan.target_agent.label)
+    table.add_row("Scope", plan.scope)
+    table.add_row("Source", str(plan.source_dir))
+    table.add_row("Destination", str(plan.target_dir))
+    table.add_row("Target exists", "yes" if plan.target_dir.exists() else "no")
+    table.add_row("Mode", "dry-run" if dry_run else "copy")
+    table.add_row("Overwrite", "yes" if force else "no")
+    console.print(table)
+    if dry_run and plan.target_dir.exists() and not force:
+        console.print("[yellow]Target already exists; actual install would need --force.[/yellow]")
+
+
+def main() -> None:
+    app()

gl_cursor_skill/core.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import shutil
+
+from .agents import AGENTS, AgentProfile, normalize_agent
+
+
+class SkillError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class SkillCandidate:
+    path: Path
+    label: str
+
+
+@dataclass(frozen=True)
+class InstallPlan:
+    source_dir: Path
+    target_dir: Path
+    skill_name: str
+    target_agent: AgentProfile
+    scope: str
+
+
+def find_skill_file(path: Path) -> Path | None:
+    if path.is_file() and path.name.lower() == "skill.md":
+        return path
+    if not path.is_dir():
+        return None
+    for name in ("SKILL.md", "skill.md"):
+        candidate = path / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def ensure_skill_dir(path: Path) -> Path:
+    expanded = path.expanduser()
+    if expanded.is_file() and expanded.name.lower() == "skill.md":
+        expanded = expanded.parent
+    skill_file = find_skill_file(expanded)
+    if skill_file is None:
+        raise SkillError(f"Not a skill directory: {expanded}")
+    return expanded
+
+
+def target_base_dir(
+    agent: AgentProfile,
+    scope: str,
+    project_root: Path | None = None,
+    explicit_dest: Path | None = None,
+) -> Path:
+    if explicit_dest is not None:
+        return explicit_dest.expanduser()
+
+    normalized_scope = normalize_scope(scope)
+    if normalized_scope == "global":
+        return agent.global_dir
+
+    root = project_root.expanduser() if project_root is not None else Path.cwd()
+    return root / agent.project_dir
+
+
+def normalize_scope(value: str) -> str:
+    normalized = value.strip().lower()
+    if normalized not in {"global", "project"}:
+        raise ValueError("Scope must be either 'global' or 'project'")
+    return normalized
+
+
+def known_source_dirs(project_root: Path | None = None) -> list[SkillCandidate]:
+    root = project_root.expanduser() if project_root is not None else Path.cwd()
+    candidates: list[SkillCandidate] = []
+
+    for agent in AGENTS:
+        candidates.append(SkillCandidate(agent.global_dir, f"{agent.label} global"))
+        candidates.append(SkillCandidate(root / agent.project_dir, f"{agent.label} project"))
+
+    return candidates
+
+
+def resolve_source_candidates(
+    skill: str,
+    source: str | None = None,
+    project_root: Path | None = None,
+) -> list[SkillCandidate]:
+    skill_path = Path(skill).expanduser()
+    if skill_path.exists():
+        source_dir = ensure_skill_dir(skill_path)
+        return [SkillCandidate(source_dir, "explicit path")]
+
+    source_path = Path(source).expanduser() if source else None
+    if source_path is not None and source_path.exists():
+        if find_skill_file(source_path) is not None:
+            source_dir = ensure_skill_dir(source_path)
+        elif source_path.is_dir():
+            source_dir = ensure_skill_dir(source_path / skill)
+        else:
+            source_dir = ensure_skill_dir(source_path)
+        return [SkillCandidate(source_dir, "explicit --from path")]
+
+    search_dirs = _source_search_dirs(source, project_root)
+    found: list[SkillCandidate] = []
+    seen: set[Path] = set()
+    for base in search_dirs:
+        candidate_dir = base.path / skill
+        if find_skill_file(candidate_dir) is None:
+            continue
+        resolved = candidate_dir.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        found.append(SkillCandidate(candidate_dir, base.label))
+
+    return found
+
+
+def _source_search_dirs(source: str | None, project_root: Path | None) -> list[SkillCandidate]:
+    if source is None:
+        return known_source_dirs(project_root)
+
+    try:
+        agent = normalize_agent(source)
+    except ValueError as error:
+        raise SkillError(str(error)) from error
+
+    root = project_root.expanduser() if project_root is not None else Path.cwd()
+    return [
+        SkillCandidate(agent.global_dir, f"{agent.label} global"),
+        SkillCandidate(root / agent.project_dir, f"{agent.label} project"),
+    ]
+
+
+def build_install_plan(
+    source_dir: Path,
+    target_agent: AgentProfile,
+    scope: str,
+    project_root: Path | None = None,
+    explicit_dest: Path | None = None,
+) -> InstallPlan:
+    source = ensure_skill_dir(source_dir)
+    base = target_base_dir(target_agent, scope, project_root, explicit_dest)
+    return InstallPlan(
+        source_dir=source,
+        target_dir=base / source.name,
+        skill_name=source.name,
+        target_agent=target_agent,
+        scope=normalize_scope(scope),
+    )
+
+
+def install_skill(plan: InstallPlan, force: bool = False, dry_run: bool = False) -> None:
+    if plan.target_dir.exists():
+        if dry_run:
+            return
+        if not force:
+            raise SkillError(f"Target already exists: {plan.target_dir}")
+        if plan.target_dir.is_dir():
+            shutil.rmtree(plan.target_dir)
+        else:
+            plan.target_dir.unlink()
+
+    if dry_run:
+        return
+
+    plan.target_dir.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(plan.source_dir, plan.target_dir)

gl_cursor_skill-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: gl-cursor-skill
+Version: 0.1.0
+Summary: Move and install AI agent skills between Claude, Codex, Cursor, and project scopes.
+Project-URL: Homepage, https://pypi.org/project/gl-cursor-skill/
+Author: gulei
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.16.0
+Description-Content-Type: text/markdown
+
+# gl-cursor-skill
+
+`gl-cursor-skill` installs AI-agent skills between common local skill folders.
+
+Primary usage:
+
+```bash
+uvx gl-cursor-skill add cursor-agent
+```
+
+When options are omitted in an interactive terminal, the CLI asks where to install:
+
+```text
+? Install for which agent?
+  Codex
+  Cursor
+  Claude Code
+
+? Install scope?
+  Global
+  Project
+```
+
+For scripts, pass the choices explicitly:
+
+```bash
+uvx gl-cursor-skill add cursor-agent --agent codex --scope global --from claude --yes
+```
+
+## Supported Targets
+
+| Agent | Global target | Project target |
+| --- | --- | --- |
+| Codex | `~/.codex/skills` | `.codex/skills` |
+| Claude Code | `~/.claude/skills` | `.claude/skills` |
+| Cursor | `~/.cursor/skills` | `.cursor/skills` |
+
+`claude` and `claudecode` are accepted aliases for `claude-code`.
+
+## Commands
+
+```bash
+gl-cursor-skill add <skill>
+gl-cursor-skill agents
+gl-cursor-skill list
+```
+
+Examples:
+
+```bash
+# Interactive install
+uvx gl-cursor-skill add cursor-agent
+
+# Non-interactive install from Claude global skills into Codex global skills
+uvx gl-cursor-skill add cursor-agent --agent codex --scope global --from claude --yes
+
+# Install from an explicit local path
+uvx gl-cursor-skill add /path/to/cursor-agent --agent codex --scope global --yes
+
+# Preview without copying files
+uvx gl-cursor-skill add cursor-agent --agent codex --scope global --from claude --dry-run --yes
+
+# Overwrite an existing target skill
+uvx gl-cursor-skill add cursor-agent --agent codex --scope global --from claude --force --yes
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run gl-cursor-skill --help
+uv build
+```
+
+## Release From GitHub
+
+The repository includes GitHub Actions workflows:
+
+- `.github/workflows/ci.yml` runs tests and builds the package on push and pull requests.
+- `.github/workflows/publish.yml` publishes to PyPI when a GitHub Release is published.
+
+Recommended setup:
+
+1. Create a GitHub repository and push this project.
+2. On PyPI, configure a Trusted Publisher for project `gl-cursor-skill`.
+3. Use these PyPI Trusted Publisher values:
+
+```text
+Owner: <your GitHub username or org>
+Repository name: <your repo name>
+Workflow name: publish.yml
+Environment name: pypi
+```
+
+4. For each release, bump the version in `pyproject.toml`, tag the commit as `vX.Y.Z`, and publish a GitHub Release from that tag.
+
+The workflow checks that the release tag matches the package version. For example, version `0.1.0` must be released with tag `v0.1.0`.
+
+Manual local publish also works:
+
+```bash
+UV_PUBLISH_TOKEN="pypi-..." uv publish
+```
+
+If you configure PyPI Trusted Publishing in CI, `uv publish` can run without a token.

gl_cursor_skill-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+gl_cursor_skill/__init__.py,sha256=K_dSDZrbyWw2QrMcX7EYkC2dTRMhZuSlxYR4ZxNSt14,73
+gl_cursor_skill/agents.py,sha256=ypkjRZjzZ_VxjGHdZ1Geei1FutpkHl5mjeEqKrVN67o,1362
+gl_cursor_skill/cli.py,sha256=P_qeb21HgEstEe90cjDXmUry99I9QkoQ1Jop86-dSR0,8246
+gl_cursor_skill/core.py,sha256=iIS7029zinfjsTc66i67h3nZqJlLkwyj2m5Nwg5kQA4,5073
+gl_cursor_skill-0.1.0.dist-info/METADATA,sha256=YjIVtCArbebx7liBY7vFpuH1vRrmiGjU7AZWinfKS3w,3054
+gl_cursor_skill-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gl_cursor_skill-0.1.0.dist-info/entry_points.txt,sha256=a8o0l_RJH5NET2TCkOg5etbOo_fP-zy-EKH2A2mgTv8,61
+gl_cursor_skill-0.1.0.dist-info/RECORD,,

gl_cursor_skill-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

gl_cursor_skill-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gl-cursor-skill = gl_cursor_skill.cli:main