# arvind3/robot-framework-py-skill architecture

> Architecture diagram of the GitHub repository arvind3/robot-framework-py-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arvind3/robot-framework-py-skill
- Repository: https://github.com/arvind3/robot-framework-py-skill

## Overview

1. **Repository purpose**
   - This is not an application runtime; it is a **content-and-validation repository for a Robot Framework skill**.
   - Its main job is to define authoritative guidance for generating, reviewing, and refactoring Robot Framework automation across five libraries: **SeleniumLibrary, RequestsLibrary, Browser/Playwright, AppiumLibrary, and DatabaseLibrary**.

2. **Canonical skill content**
   - `SKILL.md` is the primary authored skill document.
   - It contains the golden patterns, setup guidance, pitfalls, and do/don’t rules that the skill is expected to enforce.
   - `CHANGELOG.md` records evolution of the skill.

3. **Policy and acceptance criteria**
   - The repository treats `references/acceptance-criteria.md` as a governance artifact.
   - The same acceptance criteria are mirrored under `.github/skills/robot-framework-py/references/acceptance-criteria.md`, so the skill packaging and the repo-local references stay aligned.
   - These files define what “correct” skill behavior means and are used as the basis for validation.

4. **Example suite subsystem**
   - `examples/` is the practical demonstration layer.
   - Each library gets its own directory with:
     - a **smoke** Robot suite,
     - an **enterprise** Robot suite,
     - reusable **resources**,
     - and environment-specific **variables/env.py** files.
   - This gives the repo a pattern library for resource-driven Robot automation rather than a single monolithic example.

5. **Library-specific boundaries**
   - The examples are cleanly separated by automation domain:
     - `examples/selenium/`
     - `examples/browser/`
     - `examples/requests/`
     - `examples/appium/`
     - `examples/database/`
   - Each domain has its own resource files and local test fixtures, which keeps UI, API, mobile, and database concerns isolated from each other.

6. **Validation and quality subsystem**
   - `tests/quality/test_skill_quality.py` is the main unit-style quality gate.
   - It enforces repository policy such as presence/synchronization of acceptance criteria and required skill artifacts.
   - `tests/scenarios/robot-framework-py/scenarios.yaml` defines scenario-driven checks that validate the skill behavior across planned cases, including basic usage, error handling, advanced features, and CI-friendly mock flows.

7. **End-to-end verification flow**
   - The expected validation path is:
     - update skill content and criteria,
     - run the quality tests,
     - run the scenario harness with mocks when needed,
     - then review PR evidence.
   - This means the repo’s “data flow” is mostly **documentation and validation flow**, not runtime app data flow.

8. **CI and pull-request gating**
   - `.github/workflows/ci.yml` is the main automation entry point for checks.
   - `.github/workflows/validate-skill.yml` supports skill validation.
   - `.github/pull_request_template.md` forces contributors to provide evidence for the required checks, making the quality process part of the repo’s architecture rather than an informal convention.

9. **Published documentation site**
   - `docs/` contains a static site (`index.html`, `engineering-blog.html`, `site.js`, `styles.css`).
   - `.github/workflows/deploy-pages.yml` publishes this documentation to GitHub Pages.
   - The docs site is an output surface for the skill, distinct from the skill source and test gates.

10. **Operational/configuration artifacts**
   - `agents/openai.yaml` and `analytics.config.json` are supporting configuration files rather than core logic.
   - They indicate the repo also expects agent/tooling integration and site analytics, but these are secondary to the skill content and validation pipeline.

11. **External runtime dependencies**
   - The examples are designed to be executed with the real Robot Framework ecosystem: Robot Framework itself plus the relevant library packages.
   - The Browser examples additionally depend on Playwright initialization (`rfbrowser init`), which matters because it changes the runtime setup boundary for that library.

12. **Architecture summary for a diagram**
   - The cleanest diagram would show three main layers:
     - **Authoritative skill content and policy** (`SKILL.md`, acceptance criteria, changelog),
     - **Executable examples and scenario/quality validation** (`examples/`, `tests/`),
     - **Delivery and publication** (`.github/workflows/`, `docs/` GitHub Pages).
   - The key cross-cutting flow is: **skill guidance → examples/scenarios → automated checks → published docs / PR gate**.

Main entry points: [`SKILL.md`](https://github.com/arvind3/robot-framework-py-skill/blob/main/SKILL.md) (SKILL.md), [`examples/health-check.robot`](https://github.com/arvind3/robot-framework-py-skill/blob/main/examples/health-check.robot) (Health check), [`docs/index.html`](https://github.com/arvind3/robot-framework-py-skill/blob/main/docs/index.html) (Docs site), [`references/acceptance-criteria.md`](https://github.com/arvind3/robot-framework-py-skill/blob/main/references/acceptance-criteria.md) (Criteria)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Skill content"]
  node_skill_md["SKILL.md<br/>authoritative guide<br/>[SKILL.md]"]
  node_acceptance_repo["Criteria<br/>policy spec"]
  node_acceptance_skill["Packaged criteria<br/>packaged policy"]
  node_changelog["CHANGELOG<br/>release history<br/>[CHANGELOG.md]"]
end

subgraph group_examples["Examples"]
  node_selenium_ex["Selenium<br/>UI examples"]
  node_browser_ex["Browser<br/>Playwright examples"]
  node_requests_ex["Requests<br/>API examples"]
  node_appium_ex["Appium<br/>mobile examples"]
  node_database_ex["Database<br/>DB examples"]
  node_health_check["Health check<br/>shared example<br/>[health-check.robot]"]
end

subgraph group_validation["Validation"]
  node_quality_test["Quality gate<br/>unit validation"]
  node_scenarios_yaml["Scenarios<br/>scenario matrix<br/>[scenarios.yaml]"]
end

subgraph group_delivery["Delivery"]
  node_pr_template["PR template<br/>evidence gate"]
  node_ci_workflow["CI<br/>automation workflow<br/>[ci.yml]"]
  node_validate_workflow["Validate skill<br/>automation workflow<br/>[validate-skill.yml]"]
  node_deploy_workflow["Deploy pages<br/>publishing workflow<br/>[deploy-pages.yml]"]
  node_docs_site["Docs site<br/>static site<br/>[index.html]"]
  node_docs_blog["Blog page<br/>docs page"]
end

node_agent_cfg["Agent config<br/>tooling config<br/>[openai.yaml]"]
node_analytics_cfg["Analytics<br/>site config"]

node_skill_md -->|"defines"| node_acceptance_repo
node_acceptance_repo -->|"mirrored by"| node_acceptance_skill
node_skill_md -->|"evolves"| node_changelog
node_skill_md -->|"guides"| node_selenium_ex
node_skill_md -->|"guides"| node_browser_ex
node_skill_md -->|"guides"| node_requests_ex
node_skill_md -->|"guides"| node_appium_ex
node_skill_md -->|"guides"| node_database_ex
node_selenium_ex -->|"contributes to"| node_health_check
node_browser_ex -->|"contributes to"| node_health_check
node_requests_ex -->|"contributes to"| node_health_check
node_appium_ex -->|"contributes to"| node_health_check
node_database_ex -->|"contributes to"| node_health_check
node_acceptance_repo -->|"enforced by"| node_quality_test
node_acceptance_skill -->|"enforced by"| node_quality_test
node_health_check -->|"validated by"| node_scenarios_yaml
node_quality_test -->|"runs in"| node_ci_workflow
node_scenarios_yaml -->|"runs in"| node_validate_workflow
node_pr_template -->|"requires evidence from"| node_ci_workflow
node_pr_template -->|"requires evidence from"| node_validate_workflow
node_docs_site -->|"published by"| node_deploy_workflow
node_docs_blog -->|"part of"| node_docs_site
node_analytics_cfg -->|"supports"| node_docs_site
node_agent_cfg -->|"supports"| node_skill_md
node_skill_md -->|"informs"| node_docs_site

click node_skill_md "https://github.com/arvind3/robot-framework-py-skill/blob/main/SKILL.md"
click node_acceptance_repo "https://github.com/arvind3/robot-framework-py-skill/blob/main/references/acceptance-criteria.md"
click node_acceptance_skill "https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/skills/robot-framework-py/references/acceptance-criteria.md"
click node_changelog "https://github.com/arvind3/robot-framework-py-skill/blob/main/CHANGELOG.md"
click node_selenium_ex "https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/selenium"
click node_browser_ex "https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/browser"
click node_requests_ex "https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/requests"
click node_appium_ex "https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/appium"
click node_database_ex "https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/database"
click node_health_check "https://github.com/arvind3/robot-framework-py-skill/blob/main/examples/health-check.robot"
click node_quality_test "https://github.com/arvind3/robot-framework-py-skill/blob/main/tests/quality/test_skill_quality.py"
click node_scenarios_yaml "https://github.com/arvind3/robot-framework-py-skill/blob/main/tests/scenarios/robot-framework-py/scenarios.yaml"
click node_pr_template "https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/pull_request_template.md"
click node_ci_workflow "https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/workflows/ci.yml"
click node_validate_workflow "https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/workflows/validate-skill.yml"
click node_deploy_workflow "https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/workflows/deploy-pages.yml"
click node_docs_site "https://github.com/arvind3/robot-framework-py-skill/blob/main/docs/index.html"
click node_docs_blog "https://github.com/arvind3/robot-framework-py-skill/blob/main/docs/engineering-blog.html"
click node_agent_cfg "https://github.com/arvind3/robot-framework-py-skill/blob/main/agents/openai.yaml"
click node_analytics_cfg "https://github.com/arvind3/robot-framework-py-skill/blob/main/analytics.config.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_md,node_acceptance_repo,node_acceptance_skill,node_changelog toneBlue
class node_selenium_ex,node_browser_ex,node_requests_ex,node_appium_ex,node_database_ex,node_health_check toneAmber
class node_quality_test,node_scenarios_yaml toneMint
class node_pr_template,node_ci_workflow,node_validate_workflow,node_deploy_workflow,node_docs_site,node_docs_blog toneRose
class node_agent_cfg,node_analytics_cfg toneNeutral
```

## Components

### Skill content

Authoritative guidance, policy, and release history for the Robot Framework skill.

- [SKILL.md](https://github.com/arvind3/robot-framework-py-skill/blob/main/SKILL.md): authoritative guide · Primary skill document with patterns, setup guidance, and do/don't rules. · `SKILL.md`
- [Criteria](https://github.com/arvind3/robot-framework-py-skill/blob/main/references/acceptance-criteria.md): policy spec · Repo-local acceptance criteria that define correct skill behavior. · `references/acceptance-criteria.md`
- [Packaged criteria](https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/skills/robot-framework-py/references/acceptance-criteria.md): packaged policy · Mirrored acceptance criteria used by the packaged skill reference. · `.github/skills/robot-framework-py/references/acceptance-criteria.md`
- [CHANGELOG](https://github.com/arvind3/robot-framework-py-skill/blob/main/CHANGELOG.md): release history · Evolution of the skill content and policy over time. · `CHANGELOG.md`

### Examples

Executable Robot Framework examples separated by automation domain.

- [Selenium](https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/selenium): UI examples · SeleniumLibrary example suites and shared resources. · `examples/selenium`
- [Browser](https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/browser): Playwright examples · Browser/Playwright example suites and setup. · `examples/browser`
- [Requests](https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/requests): API examples · RequestsLibrary example suites and resources. · `examples/requests`
- [Appium](https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/appium): mobile examples · AppiumLibrary example suites and mobile resources. · `examples/appium`
- [Database](https://github.com/arvind3/robot-framework-py-skill/tree/main/examples/database): DB examples · DatabaseLibrary example suites and resources. · `examples/database`
- [Health check](https://github.com/arvind3/robot-framework-py-skill/blob/main/examples/health-check.robot): shared example · Repository-wide smoke-style Robot check used as a simple cross-cutting example. · `examples/health-check.robot`

### Validation

Quality gates, scenario checks, and contributor evidence requirements.

- [Quality gate](https://github.com/arvind3/robot-framework-py-skill/blob/main/tests/quality/test_skill_quality.py): unit validation · Main repository policy test for required artifacts and synchronization. · `tests/quality/test_skill_quality.py`
- [Scenarios](https://github.com/arvind3/robot-framework-py-skill/blob/main/tests/scenarios/robot-framework-py/scenarios.yaml): scenario matrix · Scenario-driven checks covering usage, errors, advanced features, and mock flows. · `tests/scenarios/robot-framework-py/scenarios.yaml`

### Delivery

CI, validation workflows, and published documentation site.

- [PR template](https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/pull_request_template.md): evidence gate · Pull request checklist that requires validation evidence from contributors. · `.github/pull_request_template.md`
- [CI](https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/workflows/ci.yml): automation workflow · Primary continuous integration entry point for checks. · `.github/workflows/ci.yml`
- [Validate skill](https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/workflows/validate-skill.yml): automation workflow · Dedicated workflow for skill validation runs. · `.github/workflows/validate-skill.yml`
- [Deploy pages](https://github.com/arvind3/robot-framework-py-skill/blob/main/.github/workflows/deploy-pages.yml): publishing workflow · Workflow that publishes the docs site to GitHub Pages. · `.github/workflows/deploy-pages.yml`
- [Docs site](https://github.com/arvind3/robot-framework-py-skill/blob/main/docs/index.html): static site · Published documentation surface for the skill. · `docs/index.html`
- [Blog page](https://github.com/arvind3/robot-framework-py-skill/blob/main/docs/engineering-blog.html): docs page · Secondary documentation page within the published site. · `docs/engineering-blog.html`

### Other components

- [Agent config](https://github.com/arvind3/robot-framework-py-skill/blob/main/agents/openai.yaml): tooling config · Supporting configuration for agent/tool integration. · `agents/openai.yaml`
- [Analytics](https://github.com/arvind3/robot-framework-py-skill/blob/main/analytics.config.json): site config · Supporting analytics configuration for the docs or site tooling. · `analytics.config.json`

## Connections

- SKILL.md → Criteria: defines · Skill guidance is constrained by acceptance criteria.
- Criteria → Packaged criteria: mirrored by · Repo criteria are kept aligned with packaged skill criteria.
- SKILL.md → CHANGELOG: evolves · Skill changes are tracked over time.
- SKILL.md → Selenium: guides · Authoritative patterns are demonstrated in Selenium examples.
- SKILL.md → Browser: guides · Authoritative patterns are demonstrated in Browser examples.
- SKILL.md → Requests: guides · Authoritative patterns are demonstrated in Requests examples.
- SKILL.md → Appium: guides · Authoritative patterns are demonstrated in Appium examples.
- SKILL.md → Database: guides · Authoritative patterns are demonstrated in Database examples.
- Selenium → Health check: contributes to · UI examples feed the shared smoke-style check.
- Browser → Health check: contributes to · Browser examples feed the shared smoke-style check.
- Requests → Health check: contributes to · API examples feed the shared smoke-style check.
- Appium → Health check: contributes to · Mobile examples feed the shared smoke-style check.
- Database → Health check: contributes to · Database examples feed the shared smoke-style check.
- Criteria → Quality gate: enforced by · Quality tests verify policy and required artifacts.
- Packaged criteria → Quality gate: enforced by · Packaged criteria are checked by the quality gate.
- Health check → Scenarios: validated by · Shared example behavior is covered by the scenario harness.
- Quality gate → CI: runs in · Quality checks are part of CI.
- Scenarios → Validate skill: runs in · Scenario checks are executed through the validation workflow.
- PR template → CI: requires evidence from · Pull requests must show validation proof.
- PR template → Validate skill: requires evidence from · Pull requests must show validation proof.
- Docs site → Deploy pages: published by · Static docs are deployed through GitHub Pages.
- Blog page → Docs site: part of · Blog page is one surface of the published docs site.
- Analytics → Docs site: supports · Analytics configuration supports the published docs surface.
- Agent config → SKILL.md: supports · Agent/tooling configuration complements skill authoring and usage.
- SKILL.md → Docs site: informs · Canonical guidance is reflected in published documentation.
