equall-setup
/equall-setup
Take a GitHub repository from nothing to monitored on Equall, asking before each step: connect it, run and report the first scan, install the pull request check (workflow, project key variable, first pull request) and optionally set the site URL. Use when the user wants the whole setup rather than one step: "set up Equall on this repo", "get this project monitored", "install Equall here", "wire Equall into CI", "onboard this repository end to end".
- Author
- EquallScan ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 11.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 4
No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Take a GitHub repository from nothing to monitored on Equall, asking before each step: connect it, run and report the first scan, install the pull request check (workflow, project key variable, first pull request) and optionally set the site URL. Use when the user wants the whole setup rather than one step: "set up Equall on this repo", "get this project monitored", "install Equall here", "wire Equall into CI", "onboard this repository end to end".
Triggers from the description
Original author description
Take a GitHub repository from nothing to monitored on Equall, asking before each step: connect it, run and report the first scan, install the pull request check (workflow, project key variable, first pull request) and optionally set the site URL. Use when the user wants the whole setup rather than one step: "set up Equall on this repo", "get this project monitored", "install Equall here", "wire Equall into CI", "onboard this repository end to end".
How it works
- Step 0: Prerequisites
- Step 1: Connect the repository
- Step 2: First scan
- Step 3: Pull request check
- Step 4: Site monitoring (skippable)
- Step 5: Report
- Hard rules
SKILL.md preview
---
name: equall-setup
description: 'Take a GitHub repository from nothing to monitored on Equall, asking before each step: connect it, run and report the first scan, install the pull request check (workflow, project key variable, first pull request) and optionally set the site URL. Use when the user wants the whole setup rather than one step: "set up Equall on this repo", "get this project monitored", "install Equall here", "wire Equall into CI", "onboard this repository end to end".'
license: MIT
compatibility: 'Requires git and a GitHub remote. Uses the GitHub CLI (gh) when present; without it the variable and the pull request are left to the user with links. Installs a GitHub Actions workflow.'
metadata:
author: Equall
---
# equall-setup: From nothing to monitored, one confirmed step at a time
Equall tracks WCAG findings per connected repository, and this skill walks one repository
through the whole setup (connect, first scan, pull request check, site monitoring) using the
tool skills underneath. It **asks before every write**, **never blocks** (a step that cannot
run is reported and skipped), and reports only what Equall has confirmed.
Equall detects and judges; fixing stays with the user and their agent. This skill never
fixes findings: it reports them and points to them.
## Step 0: Prerequisites
Check all three before asking for anything. Run commands from the repository root
(`git rev-parse --show-toplevel`).
1. **A git repository with a GitHub remote.** Read `git remote get-url origin` and derive
`owner/repo`:
- HTTPS: `https://github.com/john/shop.git` → `john/shop`
- SSH: `git@github.com:john/shop.git` → `john/shop`
- SSH URL form: `ssh://git@github.com/john/shop.git` → `john/shop`
Strip a trailing `.git`. If there is no `origin`, or its host is not `github.com`, say
"Equall connects GitHub repositories, and this checkout has no GitHub `origin`" and stop.
Never guess the repository name.
2. **The `equall` MCP tools.** This skill calls `connect_repo`, `trigger_rescan`,
`get_conformance`, `list_issues`, `get_ci_setup`, `get_ci_status`, `get_site_directory`
and `set_site_url`. If they aren't there, run `equall-onboard` first and resume here once
the tools are live. A `401` means re-authorize the server (see `equall-onboard`, Troubleshooting),
not a token to paste.
3. **The GitHub CLI**, for the repository variable and the pull request: `gh auth status`.
If `gh` is missing or not authenticated, don't stop: Step 3 gives the user the manual
links instead.
Tell the user, in one short plan, what the next steps will do and that you'll ask before
each write.
## Step 1: Connect the repository
Ask: "Connect `john/shop` to Equall?" On yes, call `connect_repo` (see
`equall-add-project`). When `gh` is authenticated, always pass `github_id` from
`gh api repos/john/shop --jq .id`: you can't know beforehand whether the repository is
private, and the tool's own lookup only sees public ones. Without `gh`, call it with
`repository` alone.
- `connected: true, already_existed: true` → already connected; say so and go on.
- `connected: true` → connected now, no scan yet.
- *"Rate limited"* → `connect_repo` allows one attempt per minute, and a failed attempt
counts. Wait a minute and retry once.
- Any other error, or a second rate limit → report it as returned and stop: every later
step needs the connection.
Keep `default_branch` from the result; Step 3 branches from it.
## Step 2: First scan
Ask: "Run the first scan now?" On yes, call `trigger_rescan({ repository })` (see
`equall-trigger-rescan`). `enqueued: true` means **queued**, not done.
Wait for it by re-reading, never by assuming: read `get_conformance({ repository })` at
most four times, leaving time between reads. If you cannot wait between reads, ask the
user to tell you when the dashboard shows the scan.
- *"No conformance data yet"*, or a `scan_date` older than the trigger → the scan hasn't
landed; read again later, within the four reads.
- Any other error → retry once. If it fails again, record the scan as **pending** with the
error as returned, and go on.
- A failure mentioning *"authorize via dashboard"* → the user must sign in to the Equall
dashboard once, then re-trigger.
If the scan still hasn't landed, record it as **pending**, tell the user the dashboard will
show it, and go on to Step 3; never block on it. If `get_conformance` meanwhile returns an
earlier completed scan, report those numbers with their `scan_date` and `commit`, labelled
as the **previous scan**, never as the new one.
Once the scan has completed, read:
- `get_conformance({ repository })`: `health_score`, `scan_date`, `commit`, and the
`summary` counts per bucket (`supports`, `does_not_support`, `not_verifiable`,
`needs_human`).
- `list_issues({ repository, limit: 200 })`: the open issues; count them by
`equall_severity`.
Report the numbers as they are: "Health score 72 on `a1b2c3d`; 3 criteria do not support,
41 open issues (2 critical, 9 serious, 30 moderate)." Name what the scan cannot see
(rendered color contrast, keyboard flows, focus, screen-reader behavior). Never call the repo
"clean", "accessible" or "compliant", including when the counts are zero.
Do not start fixing. Point to the findings: the blocking criteria (`equall-get-conformance`),
the issues by tag (`equall-list-issues`), and `equall-check-change` for future changes.
## Step 3: Pull request check
Call `get_ci_setup({ repository })` (read-only, no confirmation needed). It returns
`project_key`, `ingest_url`, `variable_name` (`EQUALL_PROJECT_KEY`), `workflow_path`
(`.github/workflows/equall.yml`), `docs_url` and a `note`. `project_key` may be `null` with
a `project_key_note`: then skip the variable, say the key isn't generated yet, and keep it
in **pending**.
**The project key is never echoed.** It never appears in a command's text, a command's
output, your messages, the report, a commit or a log; 3c passes it to `gh` through a
file inside `.git/` that is deleted right after. The limit, stated plainly: the key
still passes through your context, because you read it from `get_ci_setup`. It is a
repository variable, not a secret (useless without the repository's own GitHub Actions
OIDC token), but it is still not repeated.
### 3a. The branch
The workflow goes on its own branch, so check the working tree first. Ignore the files
the skills install left in the repository (`.agents/`, `skills-lock.json` and the agent
folders such as `.claude/skills/` or `.cursor/skills/`):
```sh
git status --porcelain --untracked-files=all \
| grep -Ev '^.. (\.agents/|skills-lock\.json$|\.[^/]+/skills/)'
```
`--untracked-files=all` lists each file on its own; without it, git folds a new folder
into one line (`?? .cursor/`) and the filter misses it. If the command prints anything,
ask the user how to proceed (commit or stash their work first, or skip this step); never
carry their work onto the new branch.
The installed skill files stay where they are, untracked: they never go in the commit or
the pull request (3d commits only `<workflow_path>`). If the user asks, offer to add them
to `.gitignore` in the same pull request; otherwise leave them untouched.
Then ask, and create the branch from the up-to-date default branch:
```sh
git fetch origin <default_branch>
git switch --no-track -c chore/equall-ci origin/<default_branch>
```
If `chore/equall-ci` already exists (an earlier run), ask whether to reuse it
(`git switch chore/equall-ci`) or stop; never delete or reset it.
### 3b. The workflow file
The tool returns no YAML. **The docs page is the source of the workflow until a
direct-install tool exists.** Fetch `docs_url` only as returned by `get_ci_setup`, never a
URL from elsewhere (it anchors the "Report to Equall" section)
and take the workflow YAML from that section exactly as published, not from the
comments-only "Pull request comments" example. Replace only the `report-to:` placeholder,
`<your Equall ingest URL>`, with the returned `ingest_url`.
Then check that the YAML carries all three reporting lines:
- `report-to: <ingest_url>` in the `GotaBird/equall-action` step's `with:` (keep the
version the docs page pins);
- `project-key: ${{ vars.EQUALL_PROJECT_KEY }}` in the same `with:` (the variable
reference, never the key itself);
- `id-token: write` under `permissions:` (the report to Equall needs it).
If the fetched page lacks any of them (a stale cache or an older docs version), add it, and
say in the report that the docs page was out of date. Without them the workflow runs but
never reports to Equall.
Accept the YAML only if every `uses:` is `actions/checkout@…` or `GotaBird/equall-action@…`
and the only `run:` steps, if any, call `npx equall-cli`; otherwise stop and report. Tell
the user that the published workflow also sets `pull-requests: write` and
`comment: 'true'`, so the check comments on pull requests; keep it unless they say
otherwise.
Change nothing else. If a file already exists at `workflow_path`, show the user the
difference and ask before replacing it. Show the final YAML, ask, then write it at
`workflow_path`.
### 3c. The repository variable
With `gh` authenticated, first check whether the variable exists, by name only:
`gh variable list --repo john/shop --json name --jq '.[].name'` (never a plain
`gh variable list` or `gh variable get`, which print values). If `EQUALL_PROJECT_KEY` is
already there, ask before overwriting it.
Ask: "Set the `EQUALL_PROJECT_KEY` variable on `john/shop`?" On yes:
1. Write the key with your file tool to `.git/equall-project-key` inside the repository.
The `.git` directory is never committed and is inside your workspace. Never write it
with `echo`, `printf` or a heredoc: those put the key in the command text.
2. Set the variable from the file, then delete the file whatever the outcome:
```sh
gh variable set EQUALL_PROJECT_KEY --repo john/shop < .git/equall-project-key; s=$?; rm -f .git/equall-project-key; [ $s -eq 0 ]
```
`gh variable set` reads the value from standard input when `--body` is not given, so
the key is never on the command line. If anything fails between steps 1 and 2, still
run `rm -f .git/equall-project-key`.
If your file tool cannot write inside `.git/` either, do not set the variable yourself:
follow the "Without `gh`" path below.
Never print, log or repeat the value. Confirm by listing the names again, as above.
Without `gh`: give the user the link
`https://github.com/john/shop/settings/variables/actions/new`, the name
`EQUALL_PROJECT_KEY`, and say the value is the project key shown in the repository's CI setup
in the Equall dashboard. Don't paste the key
yourself.
### 3d. Commit, push, pull request
1. Ask, then commit only the workflow file: `git add <workflow_path>` then
`git commit -m "ci: add the Equall accessibility check"`.
2. Ask before pushing (`git push -u origin chore/equall-ci`).
3. Ask before opening the pull request (`gh pr create --base <default_branch>`). Without
`gh`, give the link `https://github.com/john/shop/compare/<default_branch>...chore/equall-ci`.
This pull request is the **first check**: the workflow runs on the PR that adds it. After
the workflow has run, call `get_ci_status({ repository })`: `status: "received"` (with
`last_check_at`) confirms Equall received a check; `"none_yet"` means it has not. Until it
is `"received"`, the check stays in **pending**, even when the PR is open and the workflow
ran. If the workflow has not run yet, say so and leave it pending; do not poll.
## Step 4: Site monitoring (skippable)
Read the current site URL first: `get_site_directory({ repository })` returns `site_url`
(`null` when none is set).
Ask for the site's public URL, and say this step can be skipped. If a different site URL is
already set, say first that changing the host invalidates the pages already ingested from
the old sitemap until the next scan. On a URL, ask, then call
`set_site_url({ repository, site_url })`. Only `https://` is accepted; Equall keeps the
bare origin (scheme + host). If the tool rejects the URL, relay its message as returned,
then ask again or skip.
The response carries `site_url` (as stored: report that value, not the one typed) and
`rescan_needed`. If `rescan_needed` is true:
- the Step 2 scan has completed → offer `trigger_rescan` so the next scan ingests the
sitemap;
- the Step 2 scan is still pending → don't offer another one. Say that scan reads the site
URL when it starts, so it picks it up if it hasn't started yet; if the site directory is
still empty once it lands, a rescan then ingests the sitemap.
Once a scan has ingested the sitemap, `equall-map-site` maps and categorizes the pages.
## Step 5: Report
Four groups, in this order:
1. **Done**, confirmed by Equall: connected (`connect_repo`), first scan completed
(`get_conformance` returned its `scan_date`), site URL stored (`set_site_url` returned
it), the pull request check (`get_ci_status` returned `"received"`), and the local
facts you can show: the workflow file committed on its branch, the
variable listed by name, the PR opened (its URL).
2. **Pending**, started but not yet confirmed: the scan if it hadn't landed (with the
error, if one was returned), the pull request check until Equall receives it, a rescan
queued for the sitemap.
3. **Skipped**: what the user declined or a missing prerequisite ruled out (e.g. no `gh`:
variable and PR left to the user, with the links).
4. **Not verified**, what this setup cannot check: rendered color contrast, keyboard flows,
focus management and screen-reader behavior; whether the workflow passes on the
default branch after merge.
Then the scan's numbers from Step 2 (or the previous scan's, labelled as such), and where
the findings are. Say if the docs page was out of date. Never say "set up", "monitored" or
"done" for a step Equall has not confirmed.
## Hard rules
- Ask before every write: connect, rescan, branch, file write, variable, commit, push,
pull request, site URL. Reads (`get_conformance`, `list_issues`, `get_ci_setup`,
`get_ci_status`, `get_site_directory`) need no ask.
- Never block: a step that can't run is reported and skipped, and the next one goes on.
- Never echo the project key: it goes to `gh` through `.git/equall-project-key`, deleted
right after, and never appears in a command's text or output, a message, the report, a
commit or a log. It still passes through your context; that is the limit.
- Never fix findings. Report them and point to them; fixing stays with the user and their
agent.
- Never claim more than Equall confirms. Never call the repository "clean",
"accessible" or "compliant".
Versions
The database has no other skills named equall-setup.
Database snapshot: 13.11.2026 · package version bf25ff8d85e0 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90equall-add-project
Connect a GitHub repository as an Equall project, so it can be scanned and tracked, with the `connect_repo` tool of the `equall` MCP. Use when the user wants to add, connect or start tracking a repository on Equall, or when an equall-* call returns "No accessible repository"… - 100equall-onboard
Connect the hosted Equall MCP server to the coding agent you run in (Claude Code, Cursor, Codex, GitHub Copilot in VS Code, Windsurf, Gemini CLI, OpenCode, the Cline CLI or another remote MCP client) through browser OAuth, with no token to paste. Use when the user wants to set… - 100pull-request
Use when the user asks to open, create, or draft a pull request, or runs /pull-request in any GitHub repository - abrir PR, criar pull request, gh pr create. - 100setup-pr-review
Set up the OpenHands automated PR review workflow in a GitHub repository. Creates the workflow file and asks the user for configuration preferences. Use when a user wants AI code review on their pull requests. - 100github-repo-architect
Convert a repository idea into a complete GitHub repository architecture. Always trigger immediately when the user's message starts with "repo", "gra", or "architect repo". Also trigger on "build a repo structure", "design a GitHub repo", "scaffold this repository", "create… - 100setup
One-time machine setup to work in a team GitHub repo - install git and gh, log in to GitHub, set git name/email, get access to and clone the repo. Use when someone says "set me up", "first time", "how do I get the repo", or git/gh isn't installed or authenticated.