rf-agentskills 0.4.0__tar.gz

rf_agentskills-0.4.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Local secrets (do NOT commit) — use .env.example as template
+.env
+
+# Eval harness working state (generated, not committed)
+eval/runs/
+eval/reports/
+results/
+
+# Test output
+.pytest_cache/
+output.xml
+log.html
+report.html
+*.png
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Flow state (local only)
+.claude-flow/
+.swarm/
+
+# Cross-agent skill discovery symlinks (local only)
+.codex/
+.github/skills/
+
+# VS Code extension build artifacts (generated by npm/vsce)
+vscode-extension/node_modules/
+vscode-extension/out/
+vscode-extension/*.vsix
+vscode-extension/skills/
+
+# rf-agentskills installer: _assets/ is regenerated by the hatch build
+# hook at `pip install` time from plugins/rf-agentskills/. Don't commit
+# the duplicate. Developers run `pip install -e installer/` after clone
+# to populate it.
+installer/src/rf_agentskills/_assets/

rf_agentskills-0.4.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: rf-agentskills
+Version: 0.4.0
+Summary: Cross-agent installer for Robot Framework agent skills (Claude Code, Copilot, Codex, Cursor, Goose, OpenCode, Claude Desktop)
+Project-URL: Homepage, https://github.com/manykarim/robotframework-agentskills
+Project-URL: Repository, https://github.com/manykarim/robotframework-agentskills
+Project-URL: Issues, https://github.com/manykarim/robotframework-agentskills/issues
+Author-email: Many Kasiriha <many.kasiriha@gmail.com>
+License: Apache-2.0
+Keywords: agent-skills,claude-code,cursor,github-copilot,goose,installer,openai-codex,opencode,robotframework
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Robot Framework
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rf-agentskills
+
+Cross-agent installer for Robot Framework agent skills. Ships the
+`plugins/rf-agentskills/` bundle (11 skills, 4 subagents, hooks,
+helper scripts, MCP server) and writes it into the install paths of
+seven coding agents:
+
+| Agent | Status |
+|---|---|
+| Claude Code (CLI) | full native — skills, agents, hooks, MCP |
+| GitHub Copilot (VS Code 1.108+) | full native (preview flags req'd) |
+| OpenAI Codex | skills + MCP native; subagents transformed; hooks experimental |
+| Cursor 1.7+ | skills→rules, hooks adapted, native MCP |
+| OpenCode | subagents + MCP native; skills→commands; hooks deferred |
+| Project Goose | MCP + persona text only |
+| Claude Desktop | MCP only |
+
+## Install
+
+```bash
+pipx install rf-agentskills
+rf-agentskills install --agent claude-code
+```
+
+Or for every detected agent in one shot:
+
+```bash
+rf-agentskills install --all
+```
+
+## Subcommands
+
+```
+rf-agentskills install   --agent <name> [--scope user|project] [--prefix DIR]
+                         [--what skills,agents,hooks,mcp] [--dry-run] [--force]
+rf-agentskills uninstall --agent <name>
+rf-agentskills list                # what's installed where, per the manifest
+rf-agentskills targets             # which agents are detected on this machine
+rf-agentskills doctor              # what works, what doesn't, what needs user action
+rf-agentskills version
+```
+
+See `docs/installer/proposal.md` (in the parent repo) for the full
+design, compatibility matrix, and per-agent install recipes.

rf_agentskills-0.4.0/README.md

@@ -0,0 +1,44 @@
+# rf-agentskills
+
+Cross-agent installer for Robot Framework agent skills. Ships the
+`plugins/rf-agentskills/` bundle (11 skills, 4 subagents, hooks,
+helper scripts, MCP server) and writes it into the install paths of
+seven coding agents:
+
+| Agent | Status |
+|---|---|
+| Claude Code (CLI) | full native — skills, agents, hooks, MCP |
+| GitHub Copilot (VS Code 1.108+) | full native (preview flags req'd) |
+| OpenAI Codex | skills + MCP native; subagents transformed; hooks experimental |
+| Cursor 1.7+ | skills→rules, hooks adapted, native MCP |
+| OpenCode | subagents + MCP native; skills→commands; hooks deferred |
+| Project Goose | MCP + persona text only |
+| Claude Desktop | MCP only |
+
+## Install
+
+```bash
+pipx install rf-agentskills
+rf-agentskills install --agent claude-code
+```
+
+Or for every detected agent in one shot:
+
+```bash
+rf-agentskills install --all
+```
+
+## Subcommands
+
+```
+rf-agentskills install   --agent <name> [--scope user|project] [--prefix DIR]
+                         [--what skills,agents,hooks,mcp] [--dry-run] [--force]
+rf-agentskills uninstall --agent <name>
+rf-agentskills list                # what's installed where, per the manifest
+rf-agentskills targets             # which agents are detected on this machine
+rf-agentskills doctor              # what works, what doesn't, what needs user action
+rf-agentskills version
+```
+
+See `docs/installer/proposal.md` (in the parent repo) for the full
+design, compatibility matrix, and per-agent install recipes.

rf_agentskills-0.4.0/hatch_build.py

@@ -0,0 +1,96 @@
+"""Hatch build hook: mirror plugins/rf-agentskills/ → src/rf_agentskills/_assets/.
+
+The plugin tree is the source of truth (it's what the Claude Code
+marketplace and the rf-skill-eval harness already use). The installer
+needs the *same* tree shipped inside its Python wheel so importlib can
+locate it at runtime via `files("rf_agentskills").joinpath("_assets")`.
+
+Rather than maintaining a duplicate copy in the package source, this
+hook copies the tree at build time. Editable installs (`pip install -e
+installer/`) also fire the hook the first time, populating the assets
+dir for development.
+
+Hatch invokes ``initialize`` before the build target runs.
+
+Reference: https://hatch.pypa.io/latest/plugins/build-hook/custom/
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+# The path layout assumed:
+#   <repo-root>/plugins/rf-agentskills/        ← canonical source
+#   <repo-root>/installer/                     ← this package; hatch_build.py lives here
+#   <repo-root>/installer/src/rf_agentskills/_assets/   ← mirror destination
+#
+# Hatch sets ``self.root`` to the directory containing pyproject.toml,
+# i.e. ``<repo-root>/installer``. The plugin tree therefore sits one
+# level up.
+PLUGIN_REL = Path("..") / "plugins" / "rf-agentskills"
+ASSETS_REL = Path("src") / "rf_agentskills" / "_assets"
+
+
+class CustomBuildHook(BuildHookInterface):  # type: ignore[misc]
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        plugin_src = (Path(self.root) / PLUGIN_REL).resolve()
+        assets_dst = (Path(self.root) / ASSETS_REL).resolve()
+
+        # Build flow:
+        #   1. sdist build   — runs from the repo, finds ../plugins/, copies
+        #                      it into the package's _assets/ tree, and the
+        #                      sdist tarball includes _assets/ as part of
+        #                      the package contents.
+        #   2. wheel build   — runs from an extracted sdist (no parent
+        #                      `plugins/` available). Here we *skip* the
+        #                      copy; _assets/ is already populated from
+        #                      the sdist contents and is what we want
+        #                      shipped in the wheel.
+        if not plugin_src.is_dir():
+            if assets_dst.is_dir() and any(assets_dst.rglob("SKILL.md")):
+                self.app.display_info(
+                    f"rf-agentskills: plugin source not present at "
+                    f"{plugin_src} but _assets/ is already populated "
+                    f"({_count_files(assets_dst)} files) — assuming "
+                    f"sdist→wheel build, skipping mirror step"
+                )
+                return
+            raise FileNotFoundError(
+                f"plugin source not found at {plugin_src} and no "
+                f"populated _assets/ tree at {assets_dst}; cannot build "
+                f"rf-agentskills wheel without the bundled assets"
+            )
+
+        # Wipe the previous mirror so removed files don't linger in the
+        # wheel. Use ignore_errors=True because on some filesystems the
+        # dir might not exist yet.
+        if assets_dst.exists():
+            shutil.rmtree(assets_dst, ignore_errors=True)
+
+        shutil.copytree(
+            plugin_src,
+            assets_dst,
+            ignore=shutil.ignore_patterns(
+                "__pycache__",
+                "*.pyc",
+                ".pytest_cache",
+                ".mypy_cache",
+                ".ruff_cache",
+                "*.egg-info",
+            ),
+        )
+        self.app.display_info(
+            f"rf-agentskills: mirrored {plugin_src} → {assets_dst} "
+            f"({_count_files(assets_dst)} files)"
+        )
+
+
+def _count_files(root: Path) -> int:
+    return sum(1 for p in root.rglob("*") if p.is_file())

rf_agentskills-0.4.0/pyproject.toml

@@ -0,0 +1,104 @@
+# rf-agentskills installer package.
+#
+# This is a separate Python package from the repo-root rf-skill-eval
+# evaluation harness. It bundles the plugin tree at
+# plugins/rf-agentskills/ and writes it to a target coding agent's
+# expected install paths (Claude Code, Copilot, Codex, Cursor, Goose,
+# OpenCode, Claude Desktop) — see docs/installer/proposal.md for the
+# full design.
+
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rf-agentskills"
+version = "0.4.0"
+description = "Cross-agent installer for Robot Framework agent skills (Claude Code, Copilot, Codex, Cursor, Goose, OpenCode, Claude Desktop)"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+authors = [{ name = "Many Kasiriha", email = "many.kasiriha@gmail.com" }]
+keywords = [
+    "robotframework",
+    "claude-code",
+    "github-copilot",
+    "openai-codex",
+    "cursor",
+    "goose",
+    "opencode",
+    "agent-skills",
+    "installer",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Robot Framework",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    # Keep transitive deps tiny — the installer reaches into the user's
+    # $HOME, so the smaller the supply-chain surface, the better.
+    "tomli >=2.0; python_version<'3.11'",   # TOML reads on 3.10
+    "tomli-w >=1.0",                        # TOML round-trip writes (Codex config.toml)
+    "pyyaml >=6.0",                         # YAML round-trip (Goose config.yaml)
+    "rich >=13.7",                          # nicer doctor / list output
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest >=8",
+    "pytest-cov >=5",
+    "ruff >=0.5",
+]
+
+[project.scripts]
+rf-agentskills = "rf_agentskills.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/manykarim/robotframework-agentskills"
+Repository = "https://github.com/manykarim/robotframework-agentskills"
+Issues = "https://github.com/manykarim/robotframework-agentskills/issues"
+
+[tool.hatch.build]
+# The build hook in hatch_build.py mirrors plugins/rf-agentskills/ into
+# src/rf_agentskills/_assets/ before hatchling assembles the wheel, so
+# the bundle ships inside the installable package without requiring
+# duplicate maintenance of the asset tree.
+include = [
+    "src/rf_agentskills/**",
+    "README.md",
+    "hatch_build.py",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rf_agentskills"]
+
+[tool.hatch.build.targets.sdist]
+# `_assets/` is gitignored at the repo level (it's regenerated by the
+# build hook from ../plugins/rf-agentskills/), but at sdist build time
+# the hook has already populated it inside `src/rf_agentskills/`.
+# The wildcard below picks up the now-populated tree so the sdist
+# tarball is self-contained — wheel-build-from-sdist doesn't need
+# access to ../plugins/ anymore.
+include = [
+    "src/rf_agentskills/**",
+    "hatch_build.py",
+    "README.md",
+    "pyproject.toml",
+]
+
+[tool.hatch.build.hooks.custom]
+# Custom build hook resolves to <package-root>/hatch_build.py per
+# https://hatch.pypa.io/latest/plugins/build-hook/custom/.
+path = "hatch_build.py"
+
+[tool.pytest.ini_options]
+testpaths = ["../tests/installer"]
+asyncio_mode = "auto"

rf_agentskills-0.4.0/src/rf_agentskills/__init__.py

@@ -0,0 +1,15 @@
+"""rf-agentskills — cross-agent installer for Robot Framework agent skills.
+
+The package bundles the plugin tree (skills, subagents, hooks, scripts,
+MCP server) inside ``rf_agentskills/_assets/`` and provides per-agent
+adapters that copy / transform that tree into each target's expected
+install paths.
+
+See ``docs/installer/proposal.md`` (in the source repo) for the full
+design and compatibility matrix.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.4.0"
+__all__ = ("__version__",)

rf_agentskills-0.4.0/src/rf_agentskills/_assets/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "rf-agentskills",
+  "version": "1.2.0",
+  "description": "Robot Framework agent skills for Claude Code - library references, test/keyword/resource generators, libdoc search, and results analysis",
+  "author": {
+    "name": "manykarim",
+    "email": "manykarim@users.noreply.github.com"
+  },
+  "homepage": "https://github.com/manykarim/robotframework-agentskills",
+  "repository": "https://github.com/manykarim/robotframework-agentskills",
+  "license": "Apache-2.0",
+  "keywords": [
+    "robotframework",
+    "testing",
+    "automation",
+    "web-testing",
+    "api-testing",
+    "mobile-testing",
+    "playwright",
+    "selenium",
+    "appium",
+    "requests",
+    "restinstance"
+  ]
+}

rf_agentskills-0.4.0/src/rf_agentskills/_assets/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "rf-tools": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/rf-tools-server.py"],
+      "env": {
+        "PLUGIN_ROOT": "${CLAUDE_PLUGIN_ROOT}"
+      }
+    }
+  }
+}

rf_agentskills-0.4.0/src/rf_agentskills/_assets/agents/rf-debug-expert.md

@@ -0,0 +1,130 @@
+---
+name: rf-debug-expert
+description: Diagnose and resolve Robot Framework test failures, flaky tests, environment issues, and execution errors. Invoke when the user needs to analyze output.xml results, interpret error messages, debug locator failures, fix timing issues, or understand why a test suite is failing.
+---
+
+# Robot Framework Debug Expert
+
+You are an expert at diagnosing Robot Framework test failures. You combine deep knowledge of RF internals, browser/API/mobile automation pitfalls, and systematic debugging methodology to quickly isolate and resolve issues.
+
+## Core Responsibilities
+
+1. **Failure Analysis**: Parse output.xml to extract failure messages, keyword error chains, and timing anomalies.
+2. **Root Cause Identification**: Distinguish between test bugs, application bugs, environment issues, and timing/flakiness problems.
+3. **Locator Debugging**: Diagnose element-not-found errors across Browser Library, SeleniumLibrary, and AppiumLibrary.
+4. **Timing Diagnosis**: Identify race conditions, insufficient waits, and flaky patterns.
+5. **Environment Issues**: Detect missing dependencies, driver version mismatches, and configuration problems.
+
+## Diagnostic Methodology
+
+### Step 1: Gather Evidence
+
+Use the `robotframework-results` skill to parse the output.xml:
+
+```bash
+# Via MCP tool (preferred):
+# Use the rf_results_analyze tool with sections="summary,errors"
+
+# Via command line:
+# Get failure summary
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/rf_results.py" --output output.xml --sections summary,errors --pretty
+
+# Get detailed timing for slow tests
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/rf_results.py" --output output.xml --sections timing --include-keyword-timing --pretty
+
+# Get full details including tag stats
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/rf_results.py" --output output.xml --sections all --pretty
+```
+
+### Step 2: Classify the Failure
+
+| Failure Pattern | Category | Typical Cause |
+|-----------------|----------|---------------|
+| `ElementNotFound` / `Element not found` | Locator | Wrong selector, element not rendered, iframe/shadow DOM |
+| `TimeoutError` / `timeout` | Timing | Page not loaded, AJAX pending, animation blocking |
+| `AssertionError` / `!=` / `should be` | Assertion | Wrong expected value, stale data, race condition |
+| `ConnectionError` / `refused` | Environment | Service down, wrong URL, firewall |
+| `WebDriverException` / `session` | Driver | Driver crash, version mismatch, zombie process |
+| `SKIP` with message | Precondition | Setup failed, dependency not met |
+| Random pass/fail on same test | Flakiness | Timing, shared state, external dependency |
+
+### Step 3: Investigate
+
+#### For Locator Failures
+
+1. Check if the locator strategy matches the library:
+   - Browser Library: CSS default, supports `text=`, `role=`, chained `>>`
+   - SeleniumLibrary: Requires prefix (`css=`, `xpath=`, `id=`)
+   - AppiumLibrary: Platform-specific (`accessibility_id=`, `android=`, `ios=`)
+2. Check if the element is inside an iframe or Shadow DOM.
+3. Check if the element is dynamically loaded (needs a wait).
+4. Use `robotframework-libdoc-search` to verify keyword names are correct.
+
+#### For Timing Failures
+
+1. Look for `Sleep` calls (anti-pattern -- replace with proper waits).
+2. Check if waits have adequate timeouts.
+3. Look for assertions immediately after navigation without waiting.
+4. For Browser Library: auto-wait usually suffices; check if custom `Wait For` is needed.
+5. For SeleniumLibrary: explicit `Wait Until` keywords are mandatory.
+
+#### For API Failures
+
+1. Check status code expectations (`expected_status`, `Integer response status`).
+2. Check if the response body structure matches assertions.
+3. Verify authentication headers are set correctly.
+4. Check if the API server is running and accessible.
+
+### Step 4: Recommend Fix
+
+Provide the fix as:
+1. **Immediate fix**: The specific code change to resolve the failure.
+2. **Preventive pattern**: A keyword or structure change to prevent recurrence.
+3. **Monitoring suggestion**: Tags, documentation, or logging to improve future debugging.
+
+## Flakiness Patterns and Solutions
+
+### Common Flaky Test Patterns
+
+| Pattern | Symptom | Solution |
+|---------|---------|----------|
+| AJAX race | Works locally, fails in CI | Add `Wait For Response` (Browser) or `Wait Until Element Is Visible` (Selenium) |
+| Shared state | Test B fails only after Test A | Add proper Setup/Teardown, isolate browser contexts |
+| Animation blocking | Random click failures | Wait for element stability, use `force=true` sparingly |
+| Stale element | `StaleElementReferenceException` | Re-query element before interaction (Selenium) |
+| Network latency | Timeouts in CI | Increase timeouts, add retry with `Wait Until Keyword Succeeds` |
+| Parallel interference | Tests pass alone, fail together | Isolate test data, use unique identifiers |
+
+## Available Skills
+
+| Skill | Debug Use |
+|-------|-----------|
+| `robotframework-results` | Parse output.xml for failures, timing, errors |
+| `robotframework-libdoc-search` | Verify keyword names exist in libraries |
+| `robotframework-libdoc-explain` | Check correct arguments for a keyword |
+| `robotframework-browser-skill` | Browser Library troubleshooting reference |
+| `robotframework-selenium-skill` | SeleniumLibrary troubleshooting reference |
+| `robotframework-appium-skill` | AppiumLibrary troubleshooting reference |
+| `robotframework-requests-skill` | RequestsLibrary troubleshooting reference |
+| `robotframework-restinstance-skill` | RESTinstance troubleshooting reference |
+
+## Output Format
+
+When reporting a diagnosis, structure it as:
+
+```
+FAILURE: [test name]
+CATEGORY: [Locator | Timing | Assertion | Environment | Driver | Flakiness]
+ROOT CAUSE: [one-sentence explanation]
+EVIDENCE: [relevant error message or timing data]
+FIX: [specific code change]
+PREVENTION: [pattern recommendation]
+```
+
+## Constraints
+
+- Always start by parsing output.xml with the results skill before guessing.
+- Never recommend `Sleep` as a fix; use proper wait mechanisms.
+- When multiple tests fail, look for common root causes before analyzing individually.
+- When the same test fails intermittently, classify as flakiness and recommend structural fixes, not just increased timeouts.
+- Reference the appropriate library troubleshooting guide from the skill references when needed.