From e4e0f7fb9d7919fb7a8b6ae38533cbe879c145a6 Mon Sep 17 00:00:00 2001
From: diego-ferrand <diego.ferrand@abstracta.com.uy>
Date: Mon, 20 Jul 2026 11:13:37 -0300
Subject: [PATCH 1/2] Add perfecto_skills tool and AI Scriptless
 getting-started skill

---
 main.py                                       |  11 +
 pyproject.toml                                |   2 +-
 .../skills/perfecto-ai-scriptless/SKILL.md    |  90 ++++++
 .../references/ai-commands.md                 |  47 +++
 .../ai-user-actions-best-practices.md         |  69 +++++
 .../ai-validations-best-practices.md          |  58 ++++
 .../ai-visual-comparison-best-practices.md    |  32 ++
 .../references/control-constructs.md          |  57 ++++
 .../references/execute-tests.md               |  33 ++
 .../references/getting-started.md             |  38 +++
 .../references/handle-tests.md                |  53 ++++
 .../references/interface.md                   |  63 ++++
 server.py                                     |   2 +
 tests/test_skills_manager_security.py         |  58 ++++
 tests/test_skills_utils_security.py           | 110 +++++++
 tools/ai_scriptless_manager.py                |   2 +-
 tools/skills_manager.py                       | 266 ++++++++++++++++
 tools/skills_utils.py                         | 289 ++++++++++++++++++
 18 files changed, 1278 insertions(+), 2 deletions(-)
 create mode 100644 resources/skills/perfecto-ai-scriptless/SKILL.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/ai-commands.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/ai-user-actions-best-practices.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/ai-validations-best-practices.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/ai-visual-comparison-best-practices.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/control-constructs.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/execute-tests.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/getting-started.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/handle-tests.md
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/interface.md
 create mode 100644 tests/test_skills_manager_security.py
 create mode 100644 tests/test_skills_utils_security.py
 create mode 100644 tools/skills_manager.py
 create mode 100644 tools/skills_utils.py

diff --git a/main.py b/main.py
index 016e47b..87d155f 100644
--- a/main.py
+++ b/main.py
@@ -70,6 +70,17 @@ def run(log_level: str = "CRITICAL"):
     instructions = """
 # Perfecto MCP Server
 
+## Proactive Knowledge Consultation
+
+- **ALWAYS consult Perfecto Skills and Help tools first** before answering questions about Perfecto features, authoring AI Scriptless tests, interpreting results, troubleshooting, or providing recommendations.
+- **Use `perfecto_skills`**: Access specialized knowledge about Perfecto capabilities (starting with AI Scriptless), best practices, and official getting-started guidance.
+- **Use `perfecto_help`**: Consult live Perfecto documentation (category_id='perfecto', subcategory_id_list=['ide'] for AI Scriptless).
+- **Golden rule**: If you're not 100% certain about something related to Perfecto, consult Skills or Help first, and if you need to search online, prioritize help.perfecto.io.
+
+## Important Guidelines
+- **Batch Operations**: When making multiple calls to the same tool, check if that tool supports a `batch` action and use it instead of separate calls.
+- **Don't assume / Don't invent**: If something is unclear, consult Skills/Help before responding.
+- **Provide resources**: Include markdown-formatted links to Perfecto help documentation when relevant.
 """
 
     mcp = FastMCP("perfecto-mcp", instructions=instructions,
diff --git a/pyproject.toml b/pyproject.toml
index 4d10b99..2a934f8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,7 +36,7 @@ where = ["."]
 include = ["tools*", "config", "models", "formatters", "resources"]
 
 [tool.setuptools.package-data]
-"resources" = ["*.png"]
+"resources" = ["**/*"]
 
 [tool.pytest.ini_options]
 pythonpath = ["."]
diff --git a/resources/skills/perfecto-ai-scriptless/SKILL.md b/resources/skills/perfecto-ai-scriptless/SKILL.md
new file mode 100644
index 0000000..f605516
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/SKILL.md
@@ -0,0 +1,90 @@
+---
+name: perfecto-ai-scriptless
+description: Getting started and authoring guidance for Perfecto AI Scriptless (Scriptless Mobile), including the workspace UI, test lifecycle, execution, control constructs, AI commands, and best practices. Use when working with AI Scriptless for (1) Understanding the interface and how to access it, (2) Creating, opening, saving, or deleting tests, (3) Adding commands, checkpoints, loops, conditions, or logical steps, (4) Executing tests on devices, (5) Writing AI user actions, validations, or visual comparisons, (6) Using Perfecto MCP perfecto_ai_scriptless tools, or any other AI Scriptless tasks.
+---
+
+# Perfecto AI Scriptless
+
+Guides for building, running, and managing Perfecto AI Scriptless tests — with MCP tool workflows for the Perfecto MCP server.
+
+Official docs hub: [AI Scriptless interface](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-interface.htm)
+
+## Overview
+
+AI Scriptless lets you automate mobile (and, with the right licenses, desktop web) testing without writing traditional scripts. You design tests with a visual editor, predefined commands/checkpoints, and AI natural-language steps that work independently of object locators, UI language, or dynamic content.
+
+**License labeling:**
+- With Perfecto AI + Desktop Web licenses → interface labeled **AI Scriptless** (mobile + desktop web).
+- Without those licenses → labeled **Scriptless Mobile** (mobile only).
+- AI commands require a Perfecto AI license (admin feature-toggle opt-in). Without it, AI commands and related MCP operations will not work.
+
+## Quick Start
+
+1. **Access**: Perfecto landing page → Scriptless Automation → **Build ai scriptless test** (optional: select a real device).
+2. **UI**: Learn the [workspace layout](references/interface.md) (toolbar, sidebar, editor, devices, widgets, action panel).
+3. **Author**: Create/open/save tests, add AI or classic commands, use loops/conditions/logical steps.
+4. **Run**: Execute with a DUT (device under test), then open the Single Test Report.
+5. **MCP**: Prefer `perfecto_skills` + `perfecto_ai_scriptless` for programmatic authoring; use `perfecto_help` (category `perfecto` / subcategory `ide`) for live docs.
+
+## MCP Tools Integration
+
+### Skills and Help
+
+- `perfecto_skills` — `list_skills`, `read_skill` (`perfecto-ai-scriptless`), then `list_skill_resources` / `read_skill_resource_uri` for reference files.
+- `perfecto_help` — `list_help_category_content` / `read_help_info` with `category_id='perfecto'`, `subcategory_id='ide'` (or `subcategory_id_list=['ide']`).
+
+### AI Scriptless tool (`perfecto_ai_scriptless`)
+
+| Goal | Actions |
+| --- | --- |
+| Discover tests | `list_filter_values` → `list_tests` |
+| Inspect / edit structure | `view_test_structure`, `list_commands`, `get_command_definitions`, `add_command`, `modify_command`, `delete_command`, `set_command_enabled`, `move_command` |
+| Control flow | `add_logical_step`, `add_loop`, `add_condition`, `set_condition_expression` |
+| Lifecycle | `create_test`, `save_test`, `save_test_as`, `delete_test`, `move_test` |
+| Variables / history | `list_test_variables`, `add_test_variable`, `modify_test_variable`, `delete_test_variable`, `list_snapshots`, `view_snapshot` |
+| Execute | `execute_test` (after validating device via `perfecto_devices`) |
+
+### Critical MCP rules
+
+- **Licenses**: AI Scriptless MCP actions need Perfecto AI license; desktop web authoring needs Desktop Web license.
+- **step_path**: Dot-separated positional path (e.g. `0`, `2.0`, `5.b0.1`). Paths are not persisted and change after inserts/moves/deletes — always `view_test_structure` before the next structure edit.
+- **Command policy**: Call `list_commands` first and follow the selection policy in `info` before `add_command`. Prefer primary AI commands (`ai_user-action`, `ai_validation`, `ai_visual-comparison`) when authoring natural-language steps.
+- **UI access**: Lab entry is `{cloud_url}/lab/scriptless-mobile/` from `perfecto_user` `read_user`. There is no per-test URL; open tests in the UI by folder/name from `list_tests`.
+- **Not in MCP yet**: DataTables, Scheduler, Embedded tests, Object Spy, AI Assistant chat, folder rename/restore snapshot, download as Appium, and similar advanced UI features — guide users to the lab UI / help docs.
+
+### Example workflow (author + run)
+
+1. `perfecto_skills` → `read_skill` → `perfecto-ai-scriptless`
+2. `list_commands` (and `get_command_definitions` for argument shapes)
+3. `create_test` or `list_tests` → `view_test_structure`
+4. `add_command` / control-flow actions as needed; re-`view_test_structure` after each mutation
+5. Validate device (`list_real_devices` / virtual / desktop + availability checks)
+6. `execute_test` → monitor with `perfecto_execution` (`list_live_executions`, `list_report_executions`)
+
+## Reference Files
+
+### Getting started and UI
+- **[getting-started.md](references/getting-started.md)**: What AI Scriptless is, licenses, how to access
+- **[interface.md](references/interface.md)**: Top toolbar, left sidebar, test editor, devices pane, widgets, action panel
+
+### Authoring and execution
+- **[handle-tests.md](references/handle-tests.md)**: New, open, save, save as, delete, snapshots/versions
+- **[execute-tests.md](references/execute-tests.md)**: Run, stop, re-run, DUT selection, reports
+- **[control-constructs.md](references/control-constructs.md)**: Conditions, loops, logical steps
+
+### AI commands
+- **[ai-commands.md](references/ai-commands.md)**: AI commands overview and FAQ
+- **[ai-user-actions-best-practices.md](references/ai-user-actions-best-practices.md)**: Phrasing user actions, forms, install apps
+- **[ai-validations-best-practices.md](references/ai-validations-best-practices.md)**: PASS/FAIL validations, do's and don'ts
+- **[ai-visual-comparison-best-practices.md](references/ai-visual-comparison-best-practices.md)**: Visual comparison failure categories
+
+## When to Use Each Reference
+
+- **Getting started / interface**: First-time users or UI orientation questions
+- **Handle tests / execute / control constructs**: Classic Scriptless authoring and run flows
+- **AI command references**: Natural-language steps, validations, visual comparisons, licensing FAQ
+- **MCP section above**: When operating through Perfecto MCP tools instead of (or with) the lab UI
+
+## Official documentation
+
+For the full live catalog under Perfecto Help → IDE, start at [AI Scriptless](https://help.perfecto.io/perfecto-help/content/perfecto/ide/get-started-with-scriptless-mobile.htm) and use `perfecto_help` to pull any page under subcategory `ide`.
diff --git a/resources/skills/perfecto-ai-scriptless/references/ai-commands.md b/resources/skills/perfecto-ai-scriptless/references/ai-commands.md
new file mode 100644
index 0000000..f24a02e
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/ai-commands.md
@@ -0,0 +1,47 @@
+# AI commands overview and FAQ
+
+Sources:
+- [AI commands FAQ](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-ai-commands-faq.htm)
+- [AI commands](https://help.perfecto.io/perfecto-help/content/perfecto/sm-commands-and-checkpoints/ai-commands.htm)
+
+## What AI commands do
+
+AI commands (Scriptless) and AI functions (Appium) use natural language — in any language — like a conversation. Benefits:
+
+- Complex validations that may combine multiple traditional steps into one
+- Coverage beyond fragile locator-based scripting
+- Platform-agnostic steps that adapt better to UI changes
+
+In the Scriptless UI, AI commands live under the **AI** left-sidebar tab. Prefer Perfecto's AI Assistant in the lab when crafting prompts.
+
+Primary MCP command IDs (confirm via `list_commands`):
+
+- `ai_user-action` — perform actions on the DUT
+- `ai_validation` — PASS/FAIL assertions
+- `ai_visual-comparison` — screen comparison categories
+
+## Licensing FAQ
+
+- AI is **not** on by default for every Perfecto feature — only AI commands/functions.
+- A **separate Perfecto AI license** and admin **feature-toggle opt-in** are required.
+- If the org opts out later, AI-based commands cannot run and dependent tests fail.
+- Data use: see Perforce [Generative AI Policy](https://www.perforce.com/generative-ai-policy).
+
+## Limits and tips
+
+- One AI command can contain up to **30** internal steps; execution limit is **3 minutes** per call. For best results, target **≤ 15** steps.
+- Form fill / text extract with AI works on the **default tab** in web sessions (desktop browser, mobile web, WebView) — not native mobile/desktop apps, and not tabs opened mid-flow (Selenium stays on the default tab).
+- If answers are inconsistent: refine with the AI Assistant suggestions, then review best-practice docs. Ambiguous prompts are the usual cause.
+
+## Example validation conversation pattern
+
+User: "Is there a sign-up here option for new user?"  
+Assistant may suggest: "Is there a sign-up option for new users labeled 'Sign Up Here'?"
+
+Use assistant suggestions as the final validation text when possible.
+
+## Related best practices
+
+- [AI user actions](ai-user-actions-best-practices.md)
+- [AI validations](ai-validations-best-practices.md)
+- [AI visual comparisons](ai-visual-comparison-best-practices.md)
diff --git a/resources/skills/perfecto-ai-scriptless/references/ai-user-actions-best-practices.md b/resources/skills/perfecto-ai-scriptless/references/ai-user-actions-best-practices.md
new file mode 100644
index 0000000..64831af
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/ai-user-actions-best-practices.md
@@ -0,0 +1,69 @@
+# Best practices: AI user actions
+
+Source: [Best practices for working with AI user actions](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-ai-user-action-best-practices.htm)
+
+Write the action once; run across devices/OS. Describe the **logical goal**, not locators.
+
+In Scriptless, use AI commands ([AI commands](https://help.perfecto.io/perfecto-help/content/perfecto/sm-commands-and-checkpoints/ai-commands.htm)). For Appium, see [AI functions](https://help.perfecto.io/perfecto-help/content/perfecto/automation-testing/ai-functions.htm).
+
+## Performance
+
+- Phrase each User Action so it resolves to **≤ 15** steps and finishes in **under 3 minutes**.
+- Enable **Reasoning** when counting, sorting, or ordering needs extra reasoning resources.
+
+## What works well
+
+- Common UI: hamburger, help, notifications
+- Click buttons, links, icons, FABs
+- Type into empty fields or replace text
+- Radio buttons, checkboxes, sliders
+- Tabs, lists, navbars
+- Dismiss interrupting popups/notifications
+- Browser navigation (go to, back, forward, refresh, clean)
+- Install mobile apps (see install section)
+
+Still evolving / may be unreliable: inline labels relative to fields, table cell/row actions, color pickers. Not yet fully tested: append text to existing field content. LLMs can make mistakes.
+
+## Why AI user actions help
+
+- **Write once, run everywhere** — no device-specific locators
+- **Survive UI renames/moves** — goal-based instructions
+- **Wait instead of fail** — instruct wait/retry/dismiss modals/progress
+- **Focus** — “focus on / zoom into …” for dense UIs
+
+## Do's and don'ts
+
+| Don't | Do | Why |
+| --- | --- | --- |
+| Move mouse to Cart button bottom-right | On the profile page, open the shopping cart | Logical goal, not coordinates/labels |
+| Register a new account | Fill the form: Enter "Jill A. Smith" in the name fields… | Enough concrete detail |
+| Click the red shoes | From search results, select the red sneakers that cost $30 | Disambiguate similar items |
+| Pay by card | Fill the form: In the drop down, select credit card… | Triggers form-fill tooling for dropdowns |
+
+## Specialized knowledge (`ai.txt`)
+
+For domain UIs (seat maps, dashboards, canvases):
+
+1. Write instructions in plain text (max **2,000** characters; larger files are ignored).
+2. Save as `ai.txt`.
+3. Upload to the **root** of the Perfecto Repository.
+4. Reloads on login; applied as general user instructions for AI assistants/commands.
+
+## Install mobile apps via User Action
+
+Example prompts: `Install public:/path/myapp.ipa`, `Install ${myApp} on the device, open it and log in`.
+
+Configure instrumentation in the UI widget (Sensor, WebView, Secured Screen, Resign). iOS notes:
+
+- Virtual iOS: use `appname.zip`
+- Real iOS: Resign Application on by default (mandatory unless WebView changes rules)
+
+See [Install a mobile app using AI User Actions](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-ai-user-action-install-app.htm).
+
+## Fill forms
+
+Prefer **one** prompt that fills many fields, then a separate submit action.
+
+Supported: text/textarea, native `<select>`, `date` (YYYY-MM-DD), checkbox/radio, common combobox libraries.
+
+Not supported: masked inputs, custom date pickers, sliders, file upload, rich-text editors, chip/tag inputs, cross-origin iframes, closed Shadow DOM, canvas inputs.
diff --git a/resources/skills/perfecto-ai-scriptless/references/ai-validations-best-practices.md b/resources/skills/perfecto-ai-scriptless/references/ai-validations-best-practices.md
new file mode 100644
index 0000000..f08437c
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/ai-validations-best-practices.md
@@ -0,0 +1,58 @@
+# Best practices: AI validations
+
+Source: [Best practices for working with AI validations](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-ai-validations-best-practices.htm)
+
+Validations should be logical, business-oriented, and answerable from the screen (or factual public knowledge / variables).
+
+## Question vs validation
+
+| Type | Nature | Examples |
+| --- | --- | --- |
+| **Question/query** | Open-ended (what/who/where…) — **not** a validation | How much is the balance? What color is the button? |
+| **Validation** | Binary PASS/FAIL | Is the balance equal to $22? Verify the login button is green. Does user Joe appear in the header? |
+
+## Limitations
+
+- Models can err — test prompts with the AI Assistant before baking into Scriptless.
+- Not connected to your backend or “the world” beyond the screen + public facts. Time reference is environment **UTC**.
+- Enable **Reasoning** for counting/sorting/ordering.
+
+## Semantic approach
+
+AI matches meaning to what is visible (like a human tester), not DOM locators. Prefer validations that state the business meaning clearly (“available balance equals …”) rather than fragile positional guesses.
+
+## Conversation-driven assistant
+
+Use the lab AI Validation Assistant to turn ambiguous asks into objective PASS/FAIL text. Example flow:
+
+1. User: “Does the pizza costs $80?”
+2. Assistant may interpret “any pizza” and suggest a clearer sentence.
+3. User adds context (“Capsicum one?”).
+4. Assistant returns FAIL plus a precise suggestion: “Is the Capsicum pizza price equal to $80?”
+
+The assistant also fixes grammar/typos and works in many languages (best results when matching the app language).
+
+## Wait, time, variables, knowledge
+
+- Loading screens: AI validation can retry until loaded; or add a User Action “Wait for … then continue.”
+- Time: ask relative to UTC / timezone conversions.
+- Variables and factual checks are allowed if the answer is binary (`Is ${x} between 1 and 10?`).
+- Subjective questions (“tasty?”, “beautiful?”) are invalid.
+- Missing variables: Assistant may prompt and add a test variable.
+
+## Specialized knowledge
+
+Same `ai.txt` repository pattern as user actions (≤ 2,000 characters). See [ai-user-actions-best-practices.md](ai-user-actions-best-practices.md).
+
+## Do's
+
+- Be specific and objective
+- Ask about elements clearly shown on screen
+- Examples: “Do the triple black sneakers cost $601?”, “Is Nike the first in the filter list options?”
+
+## Don'ts
+
+- Subjective words (nice, clear, understood)
+- Ambiguous counts when items are partially visible or ads confuse counts
+- Vague comparatives (“much more expensive”)
+- External knowledge you cannot see (“cheaper than at Amazon”)
diff --git a/resources/skills/perfecto-ai-scriptless/references/ai-visual-comparison-best-practices.md b/resources/skills/perfecto-ai-scriptless/references/ai-visual-comparison-best-practices.md
new file mode 100644
index 0000000..7d4fec3
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/ai-visual-comparison-best-practices.md
@@ -0,0 +1,32 @@
+# Best practices: AI visual comparisons
+
+Source: [Best practices for working with AI visual comparisons](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-ai-visual-comparison-best-practices.htm)
+
+Related UI doc: [Compare screens with AI vision](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-ai-visual-comparison-assistant.htm)
+
+## What it is
+
+AI visual comparison evaluates predefined change categories between screens. You do **not** write free-form descriptions of changes to detect — categories are fixed.
+
+In Scriptless this maps to AI visual comparison commands; in Appium to AI functions.
+
+## Limitations
+
+Detectable categories are predefined for common cases. No free-form “detect this custom change” description.
+
+## Do's and don'ts
+
+**Do:** Review all detected categories in results. Select as **failure criteria** only the categories that should fail the test.
+
+**Don't:** Generally choose **Device** or **Pixel Diff** as failure categories.
+
+| Category | Why noisy |
+| --- | --- |
+| Device | Clock, battery, network status — almost always differ |
+| Pixel Diff | Compression/scaling artifacts — almost always differ |
+
+Those categories exist for rare cases where device chrome or pixel-level diffs are intentionally under test.
+
+## MCP tip
+
+When adding `ai_visual-comparison` via `add_command`, call `get_command_definitions` first and set failure categories intentionally — avoid Device/Pixel Diff unless required.
diff --git a/resources/skills/perfecto-ai-scriptless/references/control-constructs.md b/resources/skills/perfecto-ai-scriptless/references/control-constructs.md
new file mode 100644
index 0000000..b4ffedd
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/control-constructs.md
@@ -0,0 +1,57 @@
+# Conditions, loops, and logical steps
+
+Source: [Work with conditions, loops, or logical steps](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-execution-control-constructs.htm)
+
+These constructs control test execution flow. In the UI they are added from the top toolbar. In MCP use `add_condition`, `add_loop`, and `add_logical_step`.
+
+## Conditions
+
+Toolbar **Condition** icon. Splits execution into:
+
+- **On Success** (Then) — condition evaluated successfully
+- **On Failure** (Else) — error or unsuccessful evaluation
+
+Conditions evaluate the result of a statement function (including Wait). Typical pattern: put a validation (Find, Text checkpoint, AI validation, …) as the statement.
+
+Rules:
+
+- Every condition should have at most one command set as the statement.
+- Commands with nested validations cannot be the statement.
+- Without a statement, the condition will not behave as expected.
+- Setting a statement updates that command's **On Error** policy.
+- Either branch may be empty (continue after the condition).
+
+Edit parameters via the parameters pane (double-click the command).
+
+### MCP
+
+- `add_condition` — creates IfStatement with Then/Else (`b0` / `b1` in `step_path`)
+- `set_condition_expression` — set/update the expression
+- Nest steps with `parent_path` pointing at a Branch path from `view_test_structure`
+
+## Loops
+
+Toolbar **Loop** icon. Repeat a set of commands:
+
+- Fixed repetition count, or
+- Iterate a DataTable (each iteration uses the active row; automated commands)
+
+UI flow: select adjacent same-level commands → Loop → configure count, Number variable, or DataTable in the parameters pane.
+
+Only **Number** variables can drive loop counts. DataTables are UI/API advanced features — **not yet supported by Perfecto MCP**; use the lab UI for DataTable-driven loops.
+
+### MCP
+
+- `add_loop` with `count` (default 1)
+- Add child steps via `parent_path` = loop `step_path`
+
+## Logical steps
+
+Group commands into a labeled logical step (groups can nest).
+
+UI: select commands → Logical step icon. Double-click to edit parameters.
+
+### MCP
+
+- `add_logical_step` with optional `label`
+- Insert children with `parent_path`
diff --git a/resources/skills/perfecto-ai-scriptless/references/execute-tests.md b/resources/skills/perfecto-ai-scriptless/references/execute-tests.md
new file mode 100644
index 0000000..23548fe
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/execute-tests.md
@@ -0,0 +1,33 @@
+# Execute tests
+
+Source: [Execute tests](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-execute-tests.htm)
+
+You can execute a test, stop/interrupt, and re-run. The [Single test report (STR)](https://help.perfecto.io/perfecto-help/content/perfecto/test-analysis/single_test_report__str_.htm) shows command details and a video of the run.
+
+## Run an existing test (UI)
+
+1. Open the test (**Tests** → **Open**).
+2. Click **Execute test**.
+3. In **Enter runtime values**, set the **DUT** (device under test). By default DUT uses the opened device; you can select another. Desktop web DUT requires Perfecto AI + Desktop Web licenses.
+4. **Select device** → **Select** → **Run**.
+5. During run: current step is highlighted (auto-scroll); other actions are disabled; device is blocked for interaction. **Stop test** interrupts; **Re-run test** restarts.
+6. When complete, use **View report** for the STR. Failures show line numbers in the banner.
+7. Optional: dismiss the status banner with its close control.
+
+## DUT and variables
+
+A DUT variable is required to execute. Configure variables via [Configure test variables](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-configure-test-variables.htm).
+
+## MCP mapping
+
+Recommended validation before `execute_test`:
+
+1. `list_tests` — confirm `test_id` (itemKey)
+2. Resolve device by `device_type`:
+   - `real` → `list_real_devices` (+ `read_real_device_info` for availability)
+   - `virtual` → `list_virtual_devices`
+   - `desktop` → `list_desktop_devices`
+3. `execute_test` with `device_under_test`
+4. Monitor with `perfecto_execution`: `list_live_executions`, `list_report_executions` (report name ≈ test name)
+
+Stop live executions carefully (match execution name / user). Do not run on devices that are in use or malfunctioning.
diff --git a/resources/skills/perfecto-ai-scriptless/references/getting-started.md b/resources/skills/perfecto-ai-scriptless/references/getting-started.md
new file mode 100644
index 0000000..56013a2
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/getting-started.md
@@ -0,0 +1,38 @@
+# Getting started with AI Scriptless
+
+Source: [AI Scriptless](https://help.perfecto.io/perfecto-help/content/perfecto/ide/get-started-with-scriptless-mobile.htm)
+
+## What it is
+
+AI Scriptless automates application testing without writing traditional test code. You design and execute tests using a visual interface, predefined actions, and AI-powered natural-language steps. That reduces scripting while keeping flexibility for complex scenarios.
+
+Reusable components and AI-driven features help improve coverage, speed up automation, and simplify maintenance.
+
+## Licenses and product name
+
+| Cloud licenses | Interface label | Scope |
+| --- | --- | --- |
+| Perfecto AI + Desktop Web | **AI Scriptless** | Mobile and desktop web, natural-language commands |
+| Missing one or both | **Scriptless Mobile** | Mobile testing only |
+
+AI commands also require administrator opt-in (feature toggle). Without the AI license/toggle, AI commands stay inactive and tests that depend on them fail.
+
+Desktop web devices as DUT require both Perfecto AI and Desktop Web licenses.
+
+## How to access
+
+1. On the Perfecto landing page, under **Scriptless Automation**, click **Build ai scriptless test**.
+2. (Optional) In **Select device**, pick a real device and click **Select**.
+
+Lab URL pattern (also returned by MCP user info): `https://{cloud}.app.perfectomobile.com/lab/scriptless-mobile/`
+
+## CI/CD
+
+When scripts are ready, invoke them from external tools (for example Jenkins) using Perfecto API script operations. See [Script operations](https://help.perfecto.io/perfecto-help/content/perfecto/automation-testing/script_operations.htm).
+
+## Related help topics
+
+- [AI Scriptless interface](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-interface.htm)
+- [Author and manage tests](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-common-tasks.htm)
+- [Use open-device actions while authoring](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-work-with-open-device.htm)
+- [Available commands](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-commands.htm) / [Available checkpoints](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-checkpoints.htm)
diff --git a/resources/skills/perfecto-ai-scriptless/references/handle-tests.md b/resources/skills/perfecto-ai-scriptless/references/handle-tests.md
new file mode 100644
index 0000000..ea925ff
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/handle-tests.md
@@ -0,0 +1,53 @@
+# Handle tests
+
+Source: [Handle tests](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-handle-tests.htm)
+
+A test is a set of commands and checkpoints. You can create, open, save, save as, edit, and delete tests.
+
+Each save creates a new **snapshot** (version). See [Work with test versions](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-work-with-test-versions.htm).
+
+Nested constructs (loops, conditions, logical steps) appear indented with expand/collapse controls. Shortcuts (Windows and macOS): **Ctrl+]** expand all, **Ctrl+[** collapse all.
+
+## Create a new test
+
+1. Top toolbar → **Tests** → **New**
+2. Add commands and checkpoints
+3. **Tests** → **Save As**
+
+## Open an existing test
+
+1. **Tests** → **Open**
+2. Expand folders (defaults: location of open test, else Public)
+3. Optional: search by name; sort by name, dates, owner, modified by, parameters
+4. Select test → **Open**
+
+Folders: **Public Tests**, **My Tests**, and **Group Tests** (if the user belongs to a group).
+
+## Save / Save As
+
+1. **Tests** → **Save** or **Save As**
+2. For Save As: pick folder (create folders via hover + folder button; names cannot contain `\ / : * ? " < > |`)
+3. Enter name; optional comments; **Save**
+
+Every save of an existing test creates a new snapshot.
+
+## Edit steps
+
+Toolbar → **Editor Actions**: cut, copy, paste, delete, edit, or exclude lines — then save.
+
+## Delete a test
+
+1. **Tests** → **Open**
+2. Hover the test → **Delete test** → confirm **Yes**
+
+## MCP mapping
+
+| UI action | `perfecto_ai_scriptless` action |
+| --- | --- |
+| New | `create_test` |
+| Open / browse | `list_tests` (+ `list_filter_values`) |
+| Save | `save_test` (optional `comment` labels `<current>` snapshot) |
+| Save As | `save_test_as` |
+| Delete | `delete_test` |
+| Move folder | `move_test` |
+| Versions | `list_snapshots`, `view_snapshot` |
diff --git a/resources/skills/perfecto-ai-scriptless/references/interface.md b/resources/skills/perfecto-ai-scriptless/references/interface.md
new file mode 100644
index 0000000..a01d869
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/interface.md
@@ -0,0 +1,63 @@
+# AI Scriptless interface
+
+Source: [AI Scriptless interface](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-interface.htm)
+
+Use AI Scriptless to build, run, and manage tests. Control execution, select commands and checkpoints, and interact with connected devices from the main workspace.
+
+## Workspace areas
+
+| Area | Role |
+| --- | --- |
+| **Top toolbar** | Control the test and its commands |
+| **Left sidebar** | Commands, checkpoints, and embeddable tests |
+| **Test editor** | Where the test steps are listed and edited |
+| **Devices pane** | Interactive open device (similar to Manual Testing) |
+| **Widgets pane (right)** | Interact with the open device; add actions to the test and/or device |
+| **Action panel** | Basic open-device actions (home, screenshot, rotate, secure text, …) |
+
+## Top toolbar
+
+| Control | Description |
+| --- | --- |
+| **Tests** | New, open, save tests |
+| **Variables / DataTables / Scheduler** | Test variables, DataTables, scheduled jobs |
+| **Editor Actions** | Cut, Copy, Paste, Delete, Edit, Exclude |
+| **Control elements** | Loop, Logical step, Condition |
+| **Execute test** | Run the test |
+| **Open Device** | Open the selected device in the devices pane |
+
+Related: [Handle tests](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-handle-tests.htm), [Configure test variables](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-configure-test-variables.htm), [Edit tests](https://help.perfecto.io/perfecto-help/content/perfecto/ide/sm-edit-tests.htm), [Control constructs](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-execution-control-constructs.htm), [Execute tests](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-execute-tests.htm)
+
+## Left sidebar
+
+Collapsible. Tabs:
+
+| Tab | Description |
+| --- | --- |
+| **Commands** | Common commands (Home, Select text, …), **Other Commands**, and **Embeddable Tests** (repository tests). Classic commands are available when creating a test for a real mobile device. |
+| **AI** | AI Scriptless AI commands for natural-language steps independent of locators, UI language, or dynamic content. |
+
+Related: [Add commands or checkpoints](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-add-commands-or-checkpoints.htm), [AI commands](https://help.perfecto.io/perfecto-help/content/perfecto/sm-commands-and-checkpoints/ai-commands.htm)
+
+## Test editor
+
+Lists test steps (commands). Create a new test by adding commands/checkpoints, or open an existing test.
+
+## Devices pane
+
+Select a lab device and work with it like Manual Testing. Add actions to apps and/or to the test.
+
+## Action panel (open device)
+
+| Action | Notes |
+| --- | --- |
+| Close device | Release the device |
+| Home | Device home screen |
+| Lock / unlock screen | Prevent or allow interaction |
+| Take screenshot | Capture device screen |
+| Rotate | Rotate device |
+| Secure text | Enter secure text in the selected field |
+| Mute / unmute | Audio |
+| Reset device size | Reset display scale to 1:1 |
+
+Related: [Supported actions on open devices](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-supported-actions.htm), [Keyboard shortcuts](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-keyboard-shortcuts.htm)
diff --git a/server.py b/server.py
index 1600788..bff62d5 100644
--- a/server.py
+++ b/server.py
@@ -5,6 +5,7 @@
 from tools.device_manager import register as register_device_manager
 from tools.execution_manager import register as register_execution_manager
 from tools.help_manager import register as register_help_manager
+from tools.skills_manager import register as register_skills_manager
 from tools.tools_manager import register as register_tools_manager
 from tools.user_manager import register as register_user_manager
 
@@ -21,5 +22,6 @@ def register_tools(mcp, token: Optional[PerfectoToken]):
     register_device_manager(mcp, token)
     register_execution_manager(mcp, token)
     register_help_manager(mcp, token)
+    register_skills_manager(mcp, token)
     register_ai_scriptless_manager(mcp, token)
     register_tools_manager(mcp, token)
diff --git a/tests/test_skills_manager_security.py b/tests/test_skills_manager_security.py
new file mode 100644
index 0000000..013c12e
--- /dev/null
+++ b/tests/test_skills_manager_security.py
@@ -0,0 +1,58 @@
+"""
+Copyright 2025 Perforce Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import asyncio
+
+import pytest
+
+from tools import skills_utils
+from tools.skills_manager import SkillsManager
+
+
+@pytest.fixture
+def isolated_skills_resources(tmp_path, monkeypatch):
+    resources_path = tmp_path / "resources"
+    skill_dir = resources_path / "skills" / "safe-skill"
+    refs_dir = skill_dir / "references"
+    refs_dir.mkdir(parents=True)
+
+    (skill_dir / "SKILL.md").write_text(
+        "---\n"
+        "name: safe-skill\n"
+        "description: Security test skill\n"
+        "---\n",
+        encoding="utf-8",
+    )
+    (refs_dir / "guide.md").write_text("# Guide\n", encoding="utf-8")
+
+    monkeypatch.setattr(skills_utils, "get_resources_path", lambda: resources_path)
+    return resources_path
+
+
+class TestSkillsManagerListResourcesErrors:
+    def test_list_skill_resources_returns_controlled_error_for_invalid_skill_name(self, isolated_skills_resources):
+        result = asyncio.run(SkillsManager.list_skill_resources("../safe-skill"))
+
+        assert result.error is not None
+        assert "Invalid skill name" in result.error
+        assert result.result is None
+
+    def test_list_skill_resources_returns_controlled_error_for_missing_skill(self, isolated_skills_resources):
+        result = asyncio.run(SkillsManager.list_skill_resources("unknown-skill"))
+
+        assert result.error is not None
+        assert "Skill folder not found" in result.error
+        assert result.result is None
diff --git a/tests/test_skills_utils_security.py b/tests/test_skills_utils_security.py
new file mode 100644
index 0000000..be65ca0
--- /dev/null
+++ b/tests/test_skills_utils_security.py
@@ -0,0 +1,110 @@
+"""
+Copyright 2025 Perforce Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from tools import skills_utils
+
+
+@pytest.fixture
+def isolated_skills_resources(tmp_path, monkeypatch):
+    resources_path = tmp_path / "resources"
+    skill_dir = resources_path / "skills" / "safe-skill"
+    refs_dir = skill_dir / "references"
+    refs_dir.mkdir(parents=True)
+
+    (skill_dir / "SKILL.md").write_text(
+        "---\n"
+        "name: safe-skill\n"
+        "description: Security test skill\n"
+        "---\n"
+        "\n"
+        "# Skill\n",
+        encoding="utf-8",
+    )
+    (refs_dir / "guide.md").write_text("# Guide\n", encoding="utf-8")
+
+    monkeypatch.setattr(skills_utils, "get_resources_path", lambda: resources_path)
+    return resources_path
+
+
+class TestSkillsUtilsPathTraversalProtection:
+    def test_read_skill_file_rejects_parent_directory_traversal(self, isolated_skills_resources):
+        content, error = skills_utils.read_skill_file("safe-skill", "../../etc/passwd")
+
+        assert content is None
+        assert error == "Invalid file path: parent directory traversal is not allowed"
+
+    def test_read_skill_file_rejects_unix_absolute_path(self, isolated_skills_resources):
+        content, error = skills_utils.read_skill_file("safe-skill", "/etc/passwd")
+
+        assert content is None
+        assert error == "Invalid file path: absolute paths are not allowed"
+
+    def test_read_skill_file_rejects_windows_absolute_path(self, isolated_skills_resources):
+        content, error = skills_utils.read_skill_file("safe-skill", "C:/Windows/win.ini")
+
+        assert content is None
+        assert error == "Invalid file path: absolute paths are not allowed"
+
+    def test_read_skill_file_rejects_invalid_skill_name(self, isolated_skills_resources):
+        content, error = skills_utils.read_skill_file("../safe-skill", "SKILL.md")
+
+        assert content is None
+        assert error == "Invalid skill name: ../safe-skill"
+
+    def test_read_skill_file_allows_valid_relative_path(self, isolated_skills_resources):
+        content, error = skills_utils.read_skill_file("safe-skill", "references/guide.md")
+
+        assert error is None
+        assert content == "# Guide\n"
+
+
+class TestSkillUriValidation:
+    def test_is_skill_uri_rejects_path_traversal_segments(self):
+        assert not skills_utils.is_skill_uri(
+            "perfecto-skill-safe-skill://references/../../etc/passwd"
+        )
+
+    def test_parse_skill_uri_accepts_valid_uri(self):
+        skill_name, file_path = skills_utils.parse_skill_uri(
+            "perfecto-skill-safe-skill://references/guide.md"
+        )
+
+        assert skill_name == "safe-skill"
+        assert file_path == "references/guide.md"
+
+    def test_parse_skill_uri_rejects_invalid_uri(self):
+        with pytest.raises(ValueError, match="Invalid Skill URI"):
+            skills_utils.parse_skill_uri("perfecto-skill-safe-skill://../../etc/passwd")
+
+
+class TestSkillResourcesListingSecurity:
+    def test_list_skill_resources_uri_rejects_invalid_skill_name(self, isolated_skills_resources):
+        with pytest.raises(ValueError, match="Invalid skill name"):
+            skills_utils.list_skill_resources_uri("../safe-skill")
+
+    def test_list_skill_resources_uri_rejects_missing_skill_folder(self, isolated_skills_resources):
+        with pytest.raises(ValueError, match="Skill folder not found"):
+            skills_utils.list_skill_resources_uri("unknown-skill")
+
+    def test_list_skill_resources_uri_returns_only_paths_inside_skill(self, isolated_skills_resources):
+        resources = skills_utils.list_skill_resources_uri("safe-skill")
+
+        assert "perfecto-skill-safe-skill://SKILL.md" in resources
+        assert "perfecto-skill-safe-skill://references/guide.md" in resources
diff --git a/tools/ai_scriptless_manager.py b/tools/ai_scriptless_manager.py
index 15629e5..d44479c 100644
--- a/tools/ai_scriptless_manager.py
+++ b/tools/ai_scriptless_manager.py
@@ -784,7 +784,7 @@ def register(mcp, token: Optional[PerfectoToken]):
 Hints:
 - LICENSE: AI Scriptless actions require a Perfecto AI license on your cloud (administrator opt-in via feature toggle). Without it, AI commands and related MCP operations will not work. Desktop web test authoring additionally requires the Desktop Web license.
 - COVERAGE: DataTables, Scheduler (scheduled jobs), Embedded tests, and other advanced UI capabilities (folder management, rename test, restore snapshot, download as Appium, AI Assistant, Object Spy, per-step error policy, etc.) are not yet supported by this MCP tool. 
-- HELP: For product behavior and workarounds, use the perfecto_help tool: Filter by category_id='perfecto', subcategory_id_list=['ide'].
+- HELP: For product behavior and workarounds, use the perfecto_skills tool (skill `perfecto-ai-scriptless`) and/or the perfecto_help tool: Filter by category_id='perfecto', subcategory_id_list=['ide'].
 - UI_ACCESS: No per-test URL exists. Only UI entry: cloud_url/lab/scriptless-mobile/ (cloud_url from perfecto_user read_user). For debugging or unsupported MCP tasks, link the lab URL and tell the user to open the test via Tests → Open or Manage tests using the folder tree and test name from list_tests (itemKey is MCP-only; the UI shows folders and names, not itemKey). Never invent other scriptless URLs.
 - When authoring or editing test steps, call list_commands first and follow the command selection policy in the info field.
 - step_path is a dot-separated positional path without spaces (0-based indices; b0=Then branch, b1=Else). Example: root step 3 is "3"; first step inside Then of condition at 5 is "5.b0.0". Perfecto does not persist paths; they change when steps are inserted, moved, or deleted. Always call view_test_structure before the next structure edit; do not reuse step_path from a previous mutation response.
diff --git a/tools/skills_manager.py b/tools/skills_manager.py
new file mode 100644
index 0000000..1b928be
--- /dev/null
+++ b/tools/skills_manager.py
@@ -0,0 +1,266 @@
+"""
+Copyright 2025 Perforce Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+import asyncio
+import traceback
+from typing import Optional, Dict, Any, List
+from urllib.parse import unquote
+
+import httpx
+from mcp.server.fastmcp import Context
+from pydantic import Field
+
+from config.perfecto import TOOLS_PREFIX, SUPPORT_MESSAGE
+from config.token import PerfectoToken
+from models.manager import Manager
+from models.result import BaseResult
+from telemetry import run_tool
+from tools.skills_utils import list_skills, read_skill_definition, read_skill_file, parse_skill_uri, \
+    is_skill_uri, list_skill_resources_uri
+
+
+# This it's based on the ideas behind Anthropic Skills
+# More info about Skills https://github.com/anthropics/skills
+
+class SkillsManager(Manager):
+    skills = None  # Static to share between different instance of SkillsManager
+    MAX_BATCH_CONCURRENCY = 100
+    CONTENT_TRUST = "trusted"
+    CONTENT_TRUST_NOTE = (
+        "Skills content is sourced from curated repository resources and is trusted by design."
+    )
+
+    def __init__(self, token: Optional[PerfectoToken], ctx: Context):
+        super().__init__(token, ctx)
+
+    @staticmethod
+    async def list_skills() -> BaseResult:
+        errors = []
+        if SkillsManager.skills is None:
+            skills, errors = list_skills()
+            SkillsManager.skills = skills
+
+        return BaseResult(
+            result=SkillsManager.skills,
+            total=len(SkillsManager.skills),
+            has_more=False,
+            error=errors[0] if errors and len(errors) > 0 else None  # Only the first error
+        )
+
+    @staticmethod
+    async def read_skill(skill_name: Optional[str]) -> BaseResult:
+        if not isinstance(skill_name, str) or not skill_name.strip():
+            return BaseResult(
+                error="Missing required argument 'skill_name'. Please specify a non-empty skill name."
+            )
+        skill_name = skill_name.strip()
+        skill_content, error = read_skill_definition(skill_name)
+        # Trust policy note for future audits:
+        # Skills and their resources are curated project artifacts and considered trusted by design.
+        return BaseResult(
+            result=[{
+                "skill_name": skill_name,
+                "path": "SKILL.md",
+                "content": skill_content,
+                "content_trust": SkillsManager.CONTENT_TRUST,
+                "content_trust_note": SkillsManager.CONTENT_TRUST_NOTE,
+            }],
+            error=error
+        )
+
+    @staticmethod
+    async def read_skill_file_path(skill_name: str, file_path: str) -> BaseResult:
+        skill_content, error = read_skill_file(skill_name, file_path)
+        return BaseResult(
+            result=[{
+                "skill_name": skill_name,
+                "path": file_path,
+                "content": skill_content,
+                "content_trust": SkillsManager.CONTENT_TRUST,
+                "content_trust_note": SkillsManager.CONTENT_TRUST_NOTE,
+            }],
+            error=error
+        )
+
+    @staticmethod
+    async def list_skill_resources(skill_name: Optional[str]) -> BaseResult:
+        if not isinstance(skill_name, str) or not skill_name.strip():
+            return BaseResult(
+                error="Missing required argument 'skill_name'. Please specify a non-empty skill name."
+            )
+        skill_name = skill_name.strip()
+        try:
+            skill_resources = list_skill_resources_uri(skill_name)
+        except ValueError as e:
+            return BaseResult(error=str(e))
+
+        return BaseResult(
+            result=[{
+                "skill_name": skill_name,
+                "resources": skill_resources,
+                "content_trust": SkillsManager.CONTENT_TRUST,
+                "content_trust_note": SkillsManager.CONTENT_TRUST_NOTE,
+            }],
+            total=len(skill_resources),
+            has_more=False,
+        )
+
+    @staticmethod
+    async def read_skill_resource_uri(skill_uri: Optional[str]) -> BaseResult:
+        if not isinstance(skill_uri, str) or not skill_uri.strip():
+            return BaseResult(
+                error="Missing required argument 'skill_resource_uri'. Please specify a non-empty skill URI."
+            )
+        skill_uri = skill_uri.strip()
+        if is_skill_uri(skill_uri):
+            skill_name, file_path = parse_skill_uri(skill_uri)
+            skill_content, error = read_skill_file(skill_name, file_path)
+            return BaseResult(
+                result=[{
+                    "skill_name": skill_name,
+                    "path": file_path,
+                    "content": skill_content,
+                    "content_trust": SkillsManager.CONTENT_TRUST,
+                    "content_trust_note": SkillsManager.CONTENT_TRUST_NOTE,
+                }],
+                error=error
+            )
+        else:
+            return BaseResult(
+                error=f"Invalid Skill URI: {skill_uri}"
+            )
+
+    @staticmethod
+    async def read_skill_resource_uri_list(skill_uri_list: Optional[List[str]]) -> BaseResult:
+        if not isinstance(skill_uri_list, list) or not skill_uri_list:
+            return BaseResult(
+                error="Missing required argument 'skill_resource_uri_list'. Please provide a non-empty list of skill URIs."
+            )
+        results = await asyncio.gather(
+            *(SkillsManager.read_skill_resource_uri(skill_uri) for skill_uri in skill_uri_list)
+        )
+        return BaseResult(
+            result=results,
+            total=len(results),
+        )
+
+
+def register(mcp, token: Optional[PerfectoToken]):
+    @mcp.resource("perfecto-skill-{skill_name}://{path}")
+    def universal_skills_handler(skill_name: str, path: str) -> str:
+        path = unquote(path)
+        content, error = read_skill_file(skill_name, path)
+        if error:
+            return error
+        return content
+
+    @mcp.tool(
+        name=f"{TOOLS_PREFIX}_skills",
+        description="""
+Operations to obtain Skills around Perfecto.
+**Note**: If you need to call this action multiple times (even with different parameters), 
+use the `batch` action instead of making separate calls.
+Actions:
+- list_skills: List all the Skills available to learn.
+- read_skill: Read detailed information about a specific skill_name.
+    args(dict): Dictionary with the following required parameters:
+        skill_name (str): The skill name.
+- list_skill_resources: List all the Skills Resources available to learn.
+    args(dict): Dictionary with the following required parameters:
+        skill_name (str): The skill name.
+- read_skill_resource_uri: Read file content based on a Skill Resource URI (perfecto-skill-{skill_name}://{resource_path}).
+    args(dict): Dictionary with the following required parameters:
+        skill_resource_uri (str): The skill URI.
+- read_skill_resource_uri_list: Read file content based on a Skill Resource URI list (['perfecto-skill-{skill_name}://{resource_path}', ...]).
+    args(dict): Dictionary with the following required parameters:
+        skill_resource_uri_list (List[str]): The skill URI list.
+- batch: Execute multiple actions in one call.
+    args(dict): Dictionary with the following required parameters:
+        batch_calls (List[Dict]): List of Actions dictionaries (excluding the action batch), each with 'action' (str) and 'args' (Dict).
+Hints:
+- Always generates the url attributes as a link in markdown format (like command_url).
+- **CRITICAL**: For multiple actions, always use the 'batch' action.
+- **CRITICAL**: Always follow the action schema exactly. If args are required, include args with exact names/types.
+"""
+    )
+    async def skills(
+            action: str = Field(description="The action id to execute"),
+            args: Dict[str, Any] = Field(description="Dictionary with parameters", default=None),
+            ctx: Context = Field(description="Context object providing access to MCP capabilities")
+    ) -> BaseResult:
+        if args is None:
+            args = {}
+
+        skills_manager = SkillsManager(token, ctx)
+
+        async def _dispatch():
+            match action:
+                case "list_skills":
+                    return await skills_manager.list_skills()
+                case "read_skill":
+                    return await skills_manager.read_skill(args.get("skill_name"))
+                case "list_skill_resources":
+                    return await skills_manager.list_skill_resources(args.get("skill_name"))
+                case "read_skill_resource_uri":
+                    return await skills_manager.read_skill_resource_uri(args.get("skill_resource_uri"))
+                case "read_skill_resource_uri_list":
+                    return await skills_manager.read_skill_resource_uri_list(args.get("skill_resource_uri_list"))
+                case "batch":
+                    batch_calls = args.get("batch_calls", [])
+                    if not isinstance(batch_calls, list) or not batch_calls:
+                        return BaseResult(
+                            error="batch_calls must be a non-empty list of dicts with 'action' and 'args'")
+
+                    semaphore = asyncio.Semaphore(SkillsManager.MAX_BATCH_CONCURRENCY)
+
+                    async def process_call(call: Dict[str, Any]) -> BaseResult | List[BaseResult]:
+                        sub_action = call.get("action", "")
+                        sub_args = call.get("args", {})
+                        async with semaphore:
+                            try:
+                                # Recursively call the skills function itself
+                                return await skills(sub_action, sub_args, ctx)
+                            except httpx.HTTPStatusError:
+                                return BaseResult(
+                                    error=f"HTTP error in sub-action {sub_action}: {traceback.format_exc()}"
+                                )
+                            except Exception:
+                                return BaseResult(
+                                    error=f"Error in sub-action {sub_action}: {traceback.format_exc()}\n{SUPPORT_MESSAGE}")
+
+                    # Parallel execution with asyncio.gather
+                    results = await asyncio.gather(*[process_call(call) for call in batch_calls],
+                                                   return_exceptions=True)
+                    # Handle any exceptions returned
+                    processed_results = [
+                        r if not isinstance(r, Exception) else BaseResult(error=f"Unhandled exception: {str(r)}")
+                        for r in results
+                    ]
+                    return BaseResult(result=processed_results)
+                case _:
+                    return BaseResult(
+                        error=f"Action {action} not found in skills manager tool"
+                    )
+
+        try:
+            return await run_tool(f"{TOOLS_PREFIX}_skills", action, ctx, _dispatch)
+        except httpx.HTTPStatusError:
+            return BaseResult(
+                error=f"Error: {traceback.format_exc()}"
+            )
+        except Exception:
+            return BaseResult(
+                error=f"Error: {traceback.format_exc()}\n{SUPPORT_MESSAGE}"
+            )
diff --git a/tools/skills_utils.py b/tools/skills_utils.py
new file mode 100644
index 0000000..85e20ff
--- /dev/null
+++ b/tools/skills_utils.py
@@ -0,0 +1,289 @@
+"""
+Copyright 2025 Perforce Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+import os
+import re
+from pathlib import Path
+from typing import Tuple, Dict, List
+
+from config.perfecto import TOOLS_PREFIX
+from tools.utils import get_resources_path
+
+SKILL_PREFIX = f"{TOOLS_PREFIX}-skill-"
+SKILL_NAME_REGEX = re.compile(r"^[a-zA-Z0-9_-]+$")
+SKILL_URI_REGEX = re.compile(
+    rf"^{SKILL_PREFIX}(?P<skill_name>[a-zA-Z0-9_-]+)://(?P<path>(?!/)(?!.*(?:^|/)\.\.(?:/|$))[a-zA-Z0-9._/-]+)$"
+)
+
+
+def parse_frontmatter(frontmatter: str) -> Dict[str, str]:
+    meta = {}
+    lines = frontmatter.splitlines()
+    current_key = None
+    current_value = []
+    block_mode = False
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith('#'):
+            continue  # Skip empty or comment lines
+
+        if ':' in line and not line.startswith((' ', '\t')):  # New key at root level
+            if current_key:
+                value_str = '\n'.join(current_value).strip()
+                value_str = str(value_str).strip('\'"')  # Strip outer quotes if present
+                meta[current_key] = value_str
+            try:
+                key, value = [part.strip() for part in line.split(':', 1)]
+                value = str(value).strip('\'"')  # Strip quotes from single-line value
+            except ValueError:
+                raise ValueError("Invalid key-value format in frontmatter")
+
+            if key not in ('name', 'description'):
+                continue  # Ignore unexpected keys
+
+            if value in ('|', '>'):
+                block_mode = True
+                current_value = []
+            else:
+                block_mode = False
+                current_value = [value]
+
+            current_key = key
+        elif current_key and (block_mode or line.startswith((' ', '\t'))):
+            # Append to multi-line block (indented or in block mode)
+            current_value.append(line.rstrip() if block_mode else line.strip())
+        else:
+            raise ValueError("Malformed frontmatter structure")
+
+    if current_key:
+        value_str = '\n'.join(current_value).strip()
+        value_str = value_str.strip('\'"')  # Strip outer quotes if present
+        meta[current_key] = value_str
+
+    # Ensure required keys are present after parsing
+    if 'name' not in meta or 'description' not in meta:
+        raise ValueError("Missing 'name' or 'description' in frontmatter")
+
+    return meta
+
+
+def list_skills() -> Tuple[List[Dict], List[str]]:
+    full_skills_dir = os.path.join(get_resources_path(), 'skills')
+    skills = []
+    errors = []
+    skills_path = Path(full_skills_dir)
+
+    if not os.path.exists(skills_path):
+        # Graceful handling
+        return [], [f"Missing skills directory: {skills_path}"]
+
+    for folder in os.listdir(skills_path):
+        folder_path = skills_path / folder
+        if folder_path.is_dir():
+            md_path = folder_path / 'SKILL.md'
+            if md_path.exists():
+                skill, error = read_skill_meta(md_path)
+                if skill is not None:
+                    skills.append(skill)
+                if error is not None:
+                    errors.append(error)
+            else:
+                errors.append(f"Skill file not found: {md_path}")
+        else:
+            errors.append(f"Invalid Skill folder {folder_path}")
+    return skills, errors
+
+
+def validate_skill_content(content, md_path):
+    if not content.startswith('---'):
+        return False, "No YAML frontmatter found"
+
+    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+
+    frontmatter = match.group(1)
+
+    if 'name:' not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if 'description:' not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    try:
+        meta = parse_frontmatter(frontmatter)
+        name = meta.get('name')
+        description = meta.get('description')
+
+        if not name or not description:
+            return False, "Name or description is empty"
+
+        # Validate name: hyphen-case
+        if not re.match(r'^[a-z0-9-]+$', name):
+            return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
+        if name.startswith('-') or name.endswith('-') or '--' in name:
+            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+
+        # Validate description: no angle brackets
+        if '<' in description or '>' in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+
+    except ValueError as e:
+        return False, f"Error parsing frontmatter in {md_path}: {str(e)}"
+
+    return True, "Skill is valid"
+
+
+def read_skill_meta(md_path) -> Tuple[Dict[str, None], str | None]:
+    skill = None
+    error = None
+    content = md_path.read_text(encoding='utf-8')
+    valid, message = validate_skill_content(content, md_path)
+    if valid:
+        match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+        if match:
+            frontmatter = match.group(1)
+            try:
+                meta = parse_frontmatter(frontmatter)
+                name = meta.get('name')
+                description = meta.get('description')
+                if name and description:
+                    skill = {
+                        'name': name,
+                        'description': description
+                    }
+            except ValueError as e:
+                error = f"Error parsing frontmatter in {md_path}: {str(e)}"
+    else:
+        error = f"Validation failed for {md_path}: {message}"
+    return skill, error
+
+
+def get_skill_file_path(skill_name: str, file_path: str) -> Path:
+    if not SKILL_NAME_REGEX.fullmatch(skill_name):
+        raise ValueError(f"Invalid skill name: {skill_name}")
+
+    fixed_file_path = file_path.split("#")[0].strip()  # Protection against the use of anchors
+    fixed_file_path = fixed_file_path.replace("\\", "/")
+    if not fixed_file_path:
+        raise ValueError("Invalid file path: empty path")
+    if fixed_file_path.startswith("/") or re.match(r"^[a-zA-Z]:", fixed_file_path):
+        raise ValueError("Invalid file path: absolute paths are not allowed")
+
+    path_parts = Path(fixed_file_path).parts
+    if any(part == ".." for part in path_parts):
+        raise ValueError("Invalid file path: parent directory traversal is not allowed")
+
+    full_skills_dir = os.path.join(get_resources_path(), 'skills')
+    skills_path = Path(full_skills_dir)
+    skill_base_path = (skills_path / skill_name).resolve()
+    skill_file_path = (skill_base_path / fixed_file_path).resolve()
+
+    try:
+        skill_file_path.relative_to(skill_base_path)
+    except ValueError:
+        raise ValueError("Invalid file path: path traversal detected")
+
+    return skill_file_path
+
+
+def replace_skills_markdown_links(content: str, skill_name: str, file_path: str) -> str:
+    # Markdown Link Pattern []()
+    pattern = re.compile(r'\[([^\]]+)\]\(([^)]+)\)')
+
+    def replacer(match):
+        text, url = match.groups()
+        # Detect when not it's a protocol link
+        if not re.match(r'^[a-zA-Z][a-zA-Z0-9+.-]*://', url):
+            # Only when it's relative to local, generate the uri format
+            # Transform the relative path to absolute and cut the base path
+            skills_path = Path(os.path.join(get_resources_path(), 'skills'))
+            base_path = skills_path / skill_name / file_path
+            url = (base_path.parent / url).resolve()
+            try:
+                url = url.relative_to(skills_path / skill_name).as_posix()
+                new_url = f"{SKILL_PREFIX}{skill_name}://{url}"
+                return f"[{text}]({new_url})"
+            except:
+                return match.group(0)  # In case the relative not it's valid, use the original
+        else:
+            # The MCP to don't allow collision replace generic global skill with prefixed
+            new_url = url
+            if url.split("://")[0].startswith('skill-'):
+                new_url = url.replace("skill-", f"{SKILL_PREFIX}")
+            return f"[{text}]({new_url})"
+
+    return pattern.sub(replacer, content)
+
+
+def read_skill_file(skill_name: str, file_path: str) -> Tuple[str | None, str | None]:
+    try:
+        skill_file_path = get_skill_file_path(skill_name, file_path)
+    except ValueError as e:
+        return None, str(e)
+
+    if skill_file_path.exists():
+        content = skill_file_path.read_text(encoding='utf-8')
+        if file_path.endswith('.md'):  # Only on Markdown replace to skills uri format
+            content = replace_skills_markdown_links(content, skill_name, file_path)
+        if file_path.endswith('SKILL.md'):
+            valid, message = validate_skill_content(content, file_path)
+            if valid:
+                return content, None
+            else:
+                return None, f"Validation failed for {skill_name}: {message}"
+        else:
+            return content, None
+    else:
+        return None, f"Skill file not found: {file_path}"
+
+
+def is_skill_uri(uri: str) -> bool:
+    return bool(SKILL_URI_REGEX.match(uri))
+
+
+def parse_skill_uri(uri: str) -> Tuple[str, str]:
+    match = SKILL_URI_REGEX.match(uri)
+    if not match:
+        raise ValueError(f"Invalid Skill URI : {uri}")
+    return match.group("skill_name"), match.group("path")
+
+
+def list_skill_resources_uri(skill_name: str) -> List[str]:
+    if not SKILL_NAME_REGEX.fullmatch(skill_name):
+        raise ValueError(f"Invalid skill name: {skill_name}")
+
+    full_skills_dir = os.path.join(get_resources_path(), 'skills')
+    skills_path = Path(full_skills_dir).resolve()
+    skill_path = (skills_path / skill_name).resolve()
+
+    try:
+        skill_path.relative_to(skills_path)
+    except ValueError:
+        raise ValueError("Invalid skill path: path traversal detected")
+
+    if not skill_path.exists() or not skill_path.is_dir():
+        raise ValueError(f"Skill folder not found: {skill_name}")
+
+    skill_resources = []
+    for file_path in skill_path.rglob("*"):
+        if file_path.is_file():
+            url = file_path.relative_to(skill_path).as_posix()
+            skill_resources.append(f"{SKILL_PREFIX}{skill_name}://{url}")
+    return skill_resources
+
+
+def read_skill_definition(skill_name: str) -> Tuple[str | None, str | None]:
+    return read_skill_file(skill_name, 'SKILL.md')

From 27dd71f020f515d4758f7bfbcf5178b3c1a9d356 Mon Sep 17 00:00:00 2001
From: diego-ferrand <diego.ferrand@abstracta.com.uy>
Date: Thu, 23 Jul 2026 16:00:47 -0300
Subject: [PATCH 2/2] Improve AI Scriptless skill for Anthropic skill-creator
 alignment

---
 .../skills/perfecto-ai-scriptless/SKILL.md    | 140 +++++++++---------
 .../perfecto-ai-scriptless/evals/evals.json   |  40 +++++
 .../references/mcp-tools.md                   |  33 +++++
 tools/skills_utils.py                         |   3 +
 4 files changed, 148 insertions(+), 68 deletions(-)
 create mode 100644 resources/skills/perfecto-ai-scriptless/evals/evals.json
 create mode 100644 resources/skills/perfecto-ai-scriptless/references/mcp-tools.md

diff --git a/resources/skills/perfecto-ai-scriptless/SKILL.md b/resources/skills/perfecto-ai-scriptless/SKILL.md
index f605516..0e98671 100644
--- a/resources/skills/perfecto-ai-scriptless/SKILL.md
+++ b/resources/skills/perfecto-ai-scriptless/SKILL.md
@@ -1,90 +1,94 @@
 ---
 name: perfecto-ai-scriptless
-description: Getting started and authoring guidance for Perfecto AI Scriptless (Scriptless Mobile), including the workspace UI, test lifecycle, execution, control constructs, AI commands, and best practices. Use when working with AI Scriptless for (1) Understanding the interface and how to access it, (2) Creating, opening, saving, or deleting tests, (3) Adding commands, checkpoints, loops, conditions, or logical steps, (4) Executing tests on devices, (5) Writing AI user actions, validations, or visual comparisons, (6) Using Perfecto MCP perfecto_ai_scriptless tools, or any other AI Scriptless tasks.
+description: Author, run, and troubleshoot Perfecto AI Scriptless (also called Scriptless Mobile) tests — workspace UI, DUT execution, loops/conditions, AI user actions, AI validations, visual comparisons, and Perfecto MCP perfecto_ai_scriptless workflows. Use this skill whenever the user mentions AI Scriptless, Scriptless Mobile, Perfecto scriptless, natural-language test steps, AI commands, AI validation, AI user action, visual comparison, DUT, scriptless lab, or wants to create/edit/run Perfecto scriptless tests via UI or MCP — even if they do not say the exact product name.
 ---
 
 # Perfecto AI Scriptless
 
-Guides for building, running, and managing Perfecto AI Scriptless tests — with MCP tool workflows for the Perfecto MCP server.
+Teach agents how to help users with Perfecto AI Scriptless: product behavior, licenses,
+lab UI, and MCP authoring/execution. Prefer this skill over guessing.
 
 Official docs hub: [AI Scriptless interface](https://help.perfecto.io/perfecto-help/content/perfecto/ide/scriptless-mobile-interface.htm)
 
-## Overview
+## When this skill loads
 
-AI Scriptless lets you automate mobile (and, with the right licenses, desktop web) testing without writing traditional scripts. You design tests with a visual editor, predefined commands/checkpoints, and AI natural-language steps that work independently of object locators, UI language, or dynamic content.
+1. Read this `SKILL.md` first.
+2. Load only the reference files needed for the user's question (see [Reference files](#reference-files)).
+3. For live Perfecto Help pages not covered here, use `perfecto_help` with `category_id='perfecto'` and `subcategory_id='ide'`.
+4. Explain **why** a step matters when the rule prevents broken tests (licenses, `step_path`, command policy).
 
-**License labeling:**
-- With Perfecto AI + Desktop Web licenses → interface labeled **AI Scriptless** (mobile + desktop web).
-- Without those licenses → labeled **Scriptless Mobile** (mobile only).
-- AI commands require a Perfecto AI license (admin feature-toggle opt-in). Without it, AI commands and related MCP operations will not work.
+## Licenses (check early)
 
-## Quick Start
+AI Scriptless behavior depends on cloud licenses:
 
-1. **Access**: Perfecto landing page → Scriptless Automation → **Build ai scriptless test** (optional: select a real device).
-2. **UI**: Learn the [workspace layout](references/interface.md) (toolbar, sidebar, editor, devices, widgets, action panel).
-3. **Author**: Create/open/save tests, add AI or classic commands, use loops/conditions/logical steps.
-4. **Run**: Execute with a DUT (device under test), then open the Single Test Report.
-5. **MCP**: Prefer `perfecto_skills` + `perfecto_ai_scriptless` for programmatic authoring; use `perfecto_help` (category `perfecto` / subcategory `ide`) for live docs.
+| Licenses present | UI label | Scope |
+| --- | --- | --- |
+| Perfecto AI + Desktop Web | **AI Scriptless** | Mobile + desktop web, natural-language commands |
+| Missing one or both | **Scriptless Mobile** | Mobile only |
 
-## MCP Tools Integration
+- AI commands need Perfecto AI **and** admin feature-toggle opt-in. Without them, AI steps stay inactive and dependent tests fail.
+- Desktop web as DUT needs Perfecto AI **and** Desktop Web.
+- If MCP AI Scriptless calls fail with license/feature errors, tell the user to contact their Perfecto admin — do not invent workarounds.
 
-### Skills and Help
+## Quick start (UI)
 
-- `perfecto_skills` — `list_skills`, `read_skill` (`perfecto-ai-scriptless`), then `list_skill_resources` / `read_skill_resource_uri` for reference files.
-- `perfecto_help` — `list_help_category_content` / `read_help_info` with `category_id='perfecto'`, `subcategory_id='ide'` (or `subcategory_id_list=['ide']`).
+1. Open Perfecto → **Scriptless Automation** → **Build ai scriptless test** (optional: pick a real device).
+2. Lab URL: `https://{cloud}.app.perfectomobile.com/lab/scriptless-mobile/` (also from `perfecto_user` → `read_user`).
+3. Orient on the workspace — read [interface.md](references/interface.md) if the user asks about toolbar, sidebar, editor, devices, or widgets.
+4. Create/open/save tests, add AI or classic commands, then run with a DUT and open the Single Test Report.
 
-### AI Scriptless tool (`perfecto_ai_scriptless`)
+## Agent rules for MCP authoring
 
-| Goal | Actions |
+Follow these when using `perfecto_ai_scriptless` (why in parentheses):
+
+1. **Consult skills/help before inventing product behavior** — Perfecto Scriptless rules are license- and UI-specific.
+2. **Call `list_commands` before `add_command`** and follow the selection policy in the tool `info` field. Prefer primary AI commands: `ai_user-action`, `ai_validation`, `ai_visual-comparison` for natural-language steps.
+3. **Call `get_command_definitions` before filling arguments** so parameter names/types match the repository.
+4. **Treat `step_path` as ephemeral** (e.g. `0`, `2.0`, `5.b0.1`). Perfecto does not persist paths; they shift after insert/move/delete. Always `view_test_structure` before the next structure edit — never reuse a path from an older mutation response.
+5. **Re-`view_test_structure` after every structure mutation** before the next edit.
+6. **Validate the device before `execute_test`**: resolve DUT via `perfecto_devices`, check real-device availability, then execute; monitor with `perfecto_execution`.
+7. **Do not invent per-test URLs.** Only lab entry exists; open tests in the UI by folder/name from `list_tests`.
+8. **Capabilities not in MCP yet** (DataTables, Scheduler, Embedded tests, Object Spy, AI Assistant chat, restore snapshot, download as Appium, etc.): send the user to the lab UI and the matching help/reference — do not fake support.
+
+Full action catalog: [mcp-tools.md](references/mcp-tools.md).
+
+### Author + run workflow
+
+```
+1. list_commands (+ get_command_definitions as needed)
+2. create_test OR list_tests → view_test_structure
+3. add_command / add_logical_step / add_loop / add_condition …
+4. view_test_structure again after each mutation
+5. Validate device (real / virtual / desktop)
+6. execute_test → list_live_executions / list_report_executions
+```
+
+## Phrase AI steps well
+
+When helping write natural-language steps, load the matching reference:
+
+- User actions → [ai-user-actions-best-practices.md](references/ai-user-actions-best-practices.md) — describe the **goal**, not locators; keep actions ≤ ~15 internal steps / 3 minutes.
+- Validations → [ai-validations-best-practices.md](references/ai-validations-best-practices.md) — binary PASS/FAIL only, not open questions.
+- Visual comparisons → [ai-visual-comparison-best-practices.md](references/ai-visual-comparison-best-practices.md) — avoid Device / Pixel Diff as failure categories unless intentional.
+- FAQ / limits → [ai-commands.md](references/ai-commands.md)
+
+## Reference files
+
+Load on demand (one level deep):
+
+| Need | File |
 | --- | --- |
-| Discover tests | `list_filter_values` → `list_tests` |
-| Inspect / edit structure | `view_test_structure`, `list_commands`, `get_command_definitions`, `add_command`, `modify_command`, `delete_command`, `set_command_enabled`, `move_command` |
-| Control flow | `add_logical_step`, `add_loop`, `add_condition`, `set_condition_expression` |
-| Lifecycle | `create_test`, `save_test`, `save_test_as`, `delete_test`, `move_test` |
-| Variables / history | `list_test_variables`, `add_test_variable`, `modify_test_variable`, `delete_test_variable`, `list_snapshots`, `view_snapshot` |
-| Execute | `execute_test` (after validating device via `perfecto_devices`) |
-
-### Critical MCP rules
-
-- **Licenses**: AI Scriptless MCP actions need Perfecto AI license; desktop web authoring needs Desktop Web license.
-- **step_path**: Dot-separated positional path (e.g. `0`, `2.0`, `5.b0.1`). Paths are not persisted and change after inserts/moves/deletes — always `view_test_structure` before the next structure edit.
-- **Command policy**: Call `list_commands` first and follow the selection policy in `info` before `add_command`. Prefer primary AI commands (`ai_user-action`, `ai_validation`, `ai_visual-comparison`) when authoring natural-language steps.
-- **UI access**: Lab entry is `{cloud_url}/lab/scriptless-mobile/` from `perfecto_user` `read_user`. There is no per-test URL; open tests in the UI by folder/name from `list_tests`.
-- **Not in MCP yet**: DataTables, Scheduler, Embedded tests, Object Spy, AI Assistant chat, folder rename/restore snapshot, download as Appium, and similar advanced UI features — guide users to the lab UI / help docs.
-
-### Example workflow (author + run)
-
-1. `perfecto_skills` → `read_skill` → `perfecto-ai-scriptless`
-2. `list_commands` (and `get_command_definitions` for argument shapes)
-3. `create_test` or `list_tests` → `view_test_structure`
-4. `add_command` / control-flow actions as needed; re-`view_test_structure` after each mutation
-5. Validate device (`list_real_devices` / virtual / desktop + availability checks)
-6. `execute_test` → monitor with `perfecto_execution` (`list_live_executions`, `list_report_executions`)
-
-## Reference Files
-
-### Getting started and UI
-- **[getting-started.md](references/getting-started.md)**: What AI Scriptless is, licenses, how to access
-- **[interface.md](references/interface.md)**: Top toolbar, left sidebar, test editor, devices pane, widgets, action panel
-
-### Authoring and execution
-- **[handle-tests.md](references/handle-tests.md)**: New, open, save, save as, delete, snapshots/versions
-- **[execute-tests.md](references/execute-tests.md)**: Run, stop, re-run, DUT selection, reports
-- **[control-constructs.md](references/control-constructs.md)**: Conditions, loops, logical steps
-
-### AI commands
-- **[ai-commands.md](references/ai-commands.md)**: AI commands overview and FAQ
-- **[ai-user-actions-best-practices.md](references/ai-user-actions-best-practices.md)**: Phrasing user actions, forms, install apps
-- **[ai-validations-best-practices.md](references/ai-validations-best-practices.md)**: PASS/FAIL validations, do's and don'ts
-- **[ai-visual-comparison-best-practices.md](references/ai-visual-comparison-best-practices.md)**: Visual comparison failure categories
-
-## When to Use Each Reference
-
-- **Getting started / interface**: First-time users or UI orientation questions
-- **Handle tests / execute / control constructs**: Classic Scriptless authoring and run flows
-- **AI command references**: Natural-language steps, validations, visual comparisons, licensing FAQ
-- **MCP section above**: When operating through Perfecto MCP tools instead of (or with) the lab UI
+| What it is, licenses, access | [getting-started.md](references/getting-started.md) |
+| Workspace UI layout | [interface.md](references/interface.md) |
+| New/open/save/delete/versions | [handle-tests.md](references/handle-tests.md) |
+| Run / stop / DUT / reports | [execute-tests.md](references/execute-tests.md) |
+| Conditions, loops, logical steps | [control-constructs.md](references/control-constructs.md) |
+| MCP action map | [mcp-tools.md](references/mcp-tools.md) |
+| AI commands FAQ | [ai-commands.md](references/ai-commands.md) |
+| AI user-action phrasing | [ai-user-actions-best-practices.md](references/ai-user-actions-best-practices.md) |
+| AI validation phrasing | [ai-validations-best-practices.md](references/ai-validations-best-practices.md) |
+| AI visual comparison | [ai-visual-comparison-best-practices.md](references/ai-visual-comparison-best-practices.md) |
 
 ## Official documentation
 
-For the full live catalog under Perfecto Help → IDE, start at [AI Scriptless](https://help.perfecto.io/perfecto-help/content/perfecto/ide/get-started-with-scriptless-mobile.htm) and use `perfecto_help` to pull any page under subcategory `ide`.
+Live catalog: [AI Scriptless](https://help.perfecto.io/perfecto-help/content/perfecto/ide/get-started-with-scriptless-mobile.htm). Prefer `perfecto_help` for pages under subcategory `ide` when a reference is missing or may be outdated.
diff --git a/resources/skills/perfecto-ai-scriptless/evals/evals.json b/resources/skills/perfecto-ai-scriptless/evals/evals.json
new file mode 100644
index 0000000..556a8e6
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/evals/evals.json
@@ -0,0 +1,40 @@
+{
+  "skill_name": "perfecto-ai-scriptless",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm new to Perfecto — how do I open AI Scriptless and create my first test? Our cloud might only have Scriptless Mobile, not the full AI label.",
+      "expected_output": "Explains access path (Scriptless Automation → Build ai scriptless test), lab URL pattern, license labeling (AI Scriptless vs Scriptless Mobile), and a short create/save/run path. Mentions AI license/toggle for AI commands.",
+      "files": [],
+      "expectations": [
+        "Mentions Perfecto landing page or Scriptless Automation access path",
+        "Explains AI Scriptless vs Scriptless Mobile license difference",
+        "Mentions DUT or execute/run step for a first test",
+        "Does not invent a per-test deep link URL"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Using Perfecto MCP, add an AI validation step that checks the login button is green, then run the test on a free real device named something like Galaxy-S23.",
+      "expected_output": "Uses perfecto_ai_scriptless with list_commands / get_command_definitions, prefers ai_validation, phrases a PASS/FAIL validation (not an open question), view_test_structure around edits, validates device availability, then execute_test and monitoring via perfecto_execution/devices.",
+      "files": [],
+      "expectations": [
+        "Calls or describes list_commands before add_command",
+        "Uses or recommends ai_validation (not a vague open question)",
+        "Mentions view_test_structure or ephemeral step_path behavior",
+        "Includes device availability check before execute_test"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Help me phrase an AI user action for checkout: pick VISA and confirm. Also should I fail the visual comparison on Device and Pixel Diff?",
+      "expected_output": "Gives goal-based phrasing (not locator/coordinates), points at user-action best practices, and advises against Device/Pixel Diff as default failure categories for visual comparison.",
+      "files": [],
+      "expectations": [
+        "Phrasing describes logical goal rather than mouse coordinates or brittle labels alone",
+        "Warns against Device and Pixel Diff as default visual-comparison failure categories",
+        "References or applies AI user-action / visual-comparison guidance from the skill"
+      ]
+    }
+  ]
+}
diff --git a/resources/skills/perfecto-ai-scriptless/references/mcp-tools.md b/resources/skills/perfecto-ai-scriptless/references/mcp-tools.md
new file mode 100644
index 0000000..8cfe6ac
--- /dev/null
+++ b/resources/skills/perfecto-ai-scriptless/references/mcp-tools.md
@@ -0,0 +1,33 @@
+# Perfecto MCP tools for AI Scriptless
+
+Use with `perfecto_skills` (this skill) and `perfecto_ai_scriptless`. For live docs, `perfecto_help` with `category_id='perfecto'`, `subcategory_id='ide'`.
+
+## Skills and Help
+
+| Tool | Typical actions |
+| --- | --- |
+| `perfecto_skills` | `list_skills`, `read_skill` (`perfecto-ai-scriptless`), `list_skill_resources`, `read_skill_resource_uri` / `_list`, `batch` |
+| `perfecto_help` | `list_help_category_content`, `read_help_info` |
+
+## `perfecto_ai_scriptless` actions by goal
+
+| Goal | Actions |
+| --- | --- |
+| Discover tests | `list_filter_values` → `list_tests` |
+| Inspect / edit structure | `view_test_structure`, `list_commands`, `get_command_definitions`, `add_command`, `modify_command`, `delete_command`, `set_command_enabled`, `move_command` |
+| Control flow | `add_logical_step`, `add_loop`, `add_condition`, `set_condition_expression` |
+| Lifecycle | `create_test`, `save_test`, `save_test_as`, `delete_test`, `move_test` |
+| Variables / history | `list_test_variables`, `add_test_variable`, `modify_test_variable`, `delete_test_variable`, `list_snapshots`, `view_snapshot` |
+| Execute | `execute_test` (after validating device via `perfecto_devices`) |
+
+## Related tools
+
+| Tool | Use for |
+| --- | --- |
+| `perfecto_user` | Cloud URL / lab base (`…/lab/scriptless-mobile/`) |
+| `perfecto_devices` | Real / virtual / desktop DUT discovery and availability |
+| `perfecto_execution` | Live executions and reports after `execute_test` |
+
+## Not supported by MCP yet
+
+DataTables, Scheduler, Embedded tests, Object Spy, AI Assistant chat, folder rename, restore snapshot, download as Appium, and similar advanced UI features. Guide users to the lab UI and Perfecto Help instead of inventing API support.
diff --git a/tools/skills_utils.py b/tools/skills_utils.py
index 85e20ff..b975963 100644
--- a/tools/skills_utils.py
+++ b/tools/skills_utils.py
@@ -281,6 +281,9 @@ def list_skill_resources_uri(skill_name: str) -> List[str]:
     for file_path in skill_path.rglob("*"):
         if file_path.is_file():
             url = file_path.relative_to(skill_path).as_posix()
+            # Keep skill-creator eval fixtures out of agent-facing resource lists
+            if url == "evals" or url.startswith("evals/"):
+                continue
             skill_resources.append(f"{SKILL_PREFIX}{skill_name}://{url}")
     return skill_resources