AlgoForgeSkill/SKILL.md

---
name: algo-forge-skill
description: Use when working with MQL5 Algo Forge (forge.mql5.io) or any Forgejo/Gitea instance  querying repos, users, orgs, actions, pulls, issues, activity feeds, search. Activates on mentions of "algo forge", forge.mql5.io, or requests to explore/audit MQL5 Git repositories via API.
---

# Forgejo API (forge.mql5.io)

Base URL: `https://forge.mql5.io/api/v1`

## First, identify the user's environment

Before running any command, figure out whether you're on Linux/macOS/WSL
(bash/zsh), Windows PowerShell, or Windows CMD  the token-handling
commands later in this skill differ by shell, and getting it wrong either
fails outright or silently does nothing. If it's not obvious from context
(the sandbox itself, or what the user has already told you), ask.

Everything else in this skill  downloading and searching the swagger
spec, making requests  is plain Python and behaves identically across
all three, so there's no need to branch there.

## The API is large (326+ endpoints) don't memorize it, cache it and query it

The full specification lives at:
```
https://forge.mql5.io/swagger.v1.json
```

It's a standard OpenAPI/Swagger JSON, served by the instance itself and
always up to date with its real version. Don't guess endpoint paths from
memory or from a previous session  download this file once per session
and query it locally.

### `scripts/swagger_client.py` use this as-is, don't rewrite it

This is a ready utility module, not an example to reinterpret. Import it
directly:

```python
from scripts.swagger_client import load_spec, search_paths, get_path_schema

spec = load_spec()                           # Downloads once, caches for ~1h
matches = search_paths(spec, "actions")      # Find paths by keyword
schema = get_path_schema(spec, matches[0])   # Full params/response schema
```

- `load_spec()`: handles the temp folder, the download, and the cache
  expiry (1h default) on its own  call it freely, it won't re-download
  unnecessarily.
- `search_paths(spec, keyword)`: replaces grepping or memorizing URLs.
- `get_path_schema(spec, exact_path)`: gives you the exact params and HTTP
  verbs (GET/POST/PATCH/DELETE): available for that resource.
- `force_refresh()`: is there if the instance was upgraded mid-session and
  something you expect isn't showing up.

It can also be run directly for a quick lookup from the shell:
```bash
python3 scripts/swagger_client.py actions
```

### `scripts/api_request_example.py` a template, adapt it, don't run it as-is

This shows the *pattern* for calling an endpoint once you know its path
from the spec: how to test if it needs a token, how to do a plain GET,
and how to attach the `Authorization` header when needed. Copy and adapt
the relevant function to the actual path/params you need  the API has
300+ endpoints, so no single example script can cover all of them
verbatim.

```python
from scripts.api_request_example import needs_token, get_public, get_authenticated

if needs_token("/repos/search"):
    data = get_authenticated("/repos/search", {"q": "example"})
else:
    data = get_public("/repos/search", {"q": "example"})
```

## How to know if an endpoint needs a token: test it, don't assume

There is no fixed, reliable list of "this is public / this isn't". Use
`needs_token()` from `scripts/api_request_example.py`  it makes the call
without a token and checks the status code:

- `200`: it's public, you already have the data
- `401 {"message":"token is required"}`: that specific endpoint needs authentication

As a general pattern (not an absolute rule): **read** operations on
**public** repos/users/orgs (repo info, forks, commits, languages, activity
feeds, actions run history, global search) tend to respond without a token.
**Write** operations (POST/PATCH/PUT/DELETE) and a few specific admin
endpoints (secrets, runners, the dedicated collaborators endpoint) always
require a token. But confirm it case by case  we've already seen
exceptions (e.g. the `collaborators` field travels inside the public
response of `/repos/{owner}/{repo}` even though the dedicated endpoint
`/repos/{owner}/{repo}/collaborators` does require a token).

## Handling the token, if a task requires one

This is the one part that genuinely differs by shell  use the environment
you identified at the start of this skill.

Ask the user to set it themselves  never have them paste the raw token as
plain text in the chat, and never write the literal value into any file,
command output, or response.

**A. Environment variable (quick, single terminal session)**

| Environment | Set | Clear when done |
|---|---|---|
| bash/zsh (Linux, macOS, WSL) | `export FORGEJO_TOKEN="..."` | `unset FORGEJO_TOKEN` |
| PowerShell (Windows) | `$env:FORGEJO_TOKEN="..."` | `Remove-Item Env:FORGEJO_TOKEN` |
| CMD (Windows) | `set FORGEJO_TOKEN=...` | `set FORGEJO_TOKEN=` |

`scripts/api_request_example.py`'s `get_authenticated()` reads it via
`os.environ["FORGEJO_TOKEN"]`  works the same regardless of which shell
set it, as long as it's set in that session.

**B. `.env` file (better for a longer task with several scripts/steps)**

If the work spans multiple commands or scripts, a local `.env` is more
durable than a shell variable that can get lost between subprocesses:

```bash
echo 'FORGEJO_TOKEN=their-own-token-here' > .env
```

Load it in Python before calling the scripts above:
```python
from dotenv import load_dotenv
load_dotenv()
```

Whichever method is used: when the task is finished, or if you notice the
user is wrapping up / the session is ending, proactively suggest clearing
it  the shell command from the table above for the env var, or deleting
the `.env` file (`rm .env` / `Remove-Item .env`) if one was created for the
task. Don't wait to be asked.

If the user pastes the token directly into the chat despite this, don't
repeat it back in your response  use it only for that specific call, and
still suggest the proper env var / `.env` approach for anything after that.

## Other useful routes to explore without memorizing them

- `GET /repos/search?q=&sort=stars&order=desc`  search repos across the whole instance
- `GET /repos/{owner}/{repo}`  general repo info (stars, forks, license, etc.)
- `GET /repos/{owner}/{repo}/activities/feeds`  event timeline (commits, releases...)
- `GET /repos/{owner}/{repo}/actions/runs`  CI run history, if the repo has workflows under `.forgejo/workflows/`

For anything else, use `scripts/swagger_client.py` the cached spec is
the source of truth, more reliable than any fixed list in this document.