riscos-agent-skills

Guidance for registering RISC OS allocations with the RISC OS Open allocation service. Use when the user wants to register a module name, SWI chunk, error block, *command, filetype, system variable, or any other RISC OS allocation. Also use when the user asks "how do I register X", "I need to allocate X", or wants to send an allocation request to RISC OS Open.

Create, extend, review, and repair RISC OS CI pipelines, especially GitHub Actions and GitLab CI files, optional matching `.robuild.yaml` or `.robuild.yml` files for build-service jobs, 32-bit and 64-bit builds, build-service testing, artifact packaging, and draft releases. Use when Codex needs to work on `.github/workflows/*.yml`, `.gitlab-ci.yml`, `example-ci.yml`, `.robuild.yaml`, `.robuild.yml`, `riscos-project create-ci`, build.riscos.online integration, or RISC OS packaging/testing patterns for AIF, RM, and library-export projects.

Create useful pull requests or merge requests with clear reviewer-focused descriptions. Use when opening a PR or MR, especially when the description should explain the problem, summarise the changes, and record testing in a standard structure.

How to design modules for RISC OS. Use when creating new modules, designing interfaces to modules, porting a library to be used in a new module, or extending the existing interfaces of modules.

Port C projects to RISC OS using `riscos-cport`, RISC OS makefiles, and Norcroft/RISC OS build validation. Use when a repository needs a RISC OS library or command-line port, especially when you need to create a `RISCOS/` tree, generate `Makefile,fe1` files, or repair source for the RISC OS toolchain.

Read and translate RISC OS ObjAsm/ARM assembly into another language, PyModule, tests, or interface documentation. Use when converting `s/*` assembler modules, reconstructing SWI behaviour, validating comments against generated tables/disassembly, or proving binary-compatible data layout and boundary behaviour.

Commands ('*Commands') used by the RISC OS command line, in Command files (for *Exec), Obey files, OSCLI in BASIC, passed as `--command`s to `riscos-build-run`, executed within `.robuild.yaml` and `--commands` to RISC OS Pyromaniac. Use when needing to know about RISC OS commands in *Obey, OSCLI in BASIC, `.robuild.yaml` executions.

Start interactive RISC OS Filer operations through the FilerSWIs/FilerAction module by sending the `FilerAction_SendSelectedDirectory`, `FilerAction_SendSelectedFile`, and `FilerAction_SendStartOperation` SWIs in the correct order. Use this skill when Codex needs to launch desktop copy, move, delete, access, set type, count, stamp, copy-local, or find operations via the Filer action window rather than performing filesystem changes directly.

Create, review, or extend a RISC OS filer-like window interface: a Wimp window that presents selectable objects in a grid or list, redraws items on demand, supports alternate view formats, hit-testing, scrolling, and window resizing around object geometry. Use when building a file browser, media browser, picker, launcher, or any object-view modelled on the desktop Filer without needing to clone the real Filer protocol.

Information about how to interact with the RISC OS filesystem. Use when RISC OS filesystem operations are not clear, or when writing code which interacts with the RISC OS filesystem.

Create or update RISC OS image converter modules, especially ImageFileConvert converters that register source-to-destination file type pairs, implement Convert and MiscOp entry points, emit Sprite or sprite-file output, handle ImageFileConvert service startup and shutdown, or call ImageFileConvert SWIs directly to convert image buffers and files.

Describe and work with the general DCI4 statistics interface on RISC OS, including how suppliers enumerate themselves, how gatherers describe and read statistics, the provider and description structures, and common implementation patterns. Use when implementing, reviewing, documenting, or querying DCI4 statistics suppliers.

Use and explain the RISC OS Resolver module, including DNS lookups, SWIs, commands, configuration variables, cache control, service calls, and returned hostent data. Use when implementing, reviewing, documenting, or integrating with Resolver from applications or modules.

Details of how the RISC OS output system works. Use when creating text and graphics output using text positioning, graphics, drawing shapes, sprites, fonts, sprite areas, palette programming, ImageFileRender, or ColourTrans translation tables. It is not needed for plain textual output.

Reconstruct functionality, interfaces, and state machines from RISC OS module binaries. Use when you need to understand how an existing RISC OS module works or reimplement it in C.

Apply the official Acorn RISC OS Style Guide when designing, reviewing, or implementing RISC OS desktop applications. Use when Codex must check or propose classic RISC OS behaviour for desktop integration, startup and shutdown, windows, menus, dialogue boxes, icons, colour, sound, keyboard and mouse handling, selection, configuration, internationalisation, or application resource layout.

Use when adding, reviewing, or debugging RISC OS Throwback support through LibThrowback, DDEUtils_ThrowbackStart/Send/End, DDEUtils_ThrowbackRegister, or desktop editor error reporting from compilers, taskwindows, tools, and build processors.

Fetch URL or URI contents on RISC OS using the Acorn URL_Fetcher module, URL_Register, URL_GetURL, URL_Status, URL_ReadData, URL_Stop, URL_Deregister, URL_ParseURL, proxy setup, protocol enumeration, or URL fetcher protocol modules.

Launch URLs or URIs from RISC OS code, Obey files, commands, desktop applications, Wimp tasks, or modules using the AcornURI URI handler, URI_Dispatch, *URIdispatch, URI filetype &F91, or the legacy ANT URL broadcast system with wimp_MOPENURL and URLOpen scheme aliases. Treat URI and URL as interchangeable terms in RISC OS contexts.

Structure and package small RISC OS desktop Wimp applications, especially iconbar applications, without duplicating the raw Wimp protocol guidance from the riscos-wimp skill. Use when creating or restructuring a desktop application with Wimp startup, poll-loop dispatch, iconbar icons, packaged Resources files, or application naming changes.

Use when writing, reviewing, debugging, or porting RISC OS Wimp code: task initialisation and shutdown, template loading, window creation and opening, icon bar icons, icon state changes, mouse and key handling, menus, help messages, redraw/open/close event flow, or Wimp data structures and SWIs. Also use for module-specific Wimp integration such as Service_StartWimp, Desktop_ commands, or task lifecycle inside a module.

Create or update RISC OS Wimp template descriptions as `TemplateText` files using `riscos-ccres`. Use when an agent needs to build a window template from user-specified windows, follow standard RISC OS dialogue patterns, or copy bundled window template assets such as save boxes into a new template file.

Create or update AI skills in the RISC OS build environment without modifying the installed /etc copies directly. Use when a user wants to revise an existing build-environment skill, create a local working copy of a skill, derive a new skill from an existing one, create a brand new local skill for this environment, or use the `ai skill new` and `ai skill show` workflow. Prefer this skill over generic skill-creation guidance when the request is specifically about skills for this RISC OS build environment or local skill directories such as `/user/.config/ai/skills`. Always ask the user which route they want before making any skill changes.

Syntax and usage for BASIC on RISC OS. Use this whenever you are creating, editing or reviewing BASIC code (files which end in `,fd1`).

Describes the CMHG file format and CMunge usage. Use when CMHG files are required for RISC OS modules.

Use when working with GitHub-hosted repositories through the GitHub CLI in this build environment, especially for authentication checks, pull requests, Actions run inspection, release inspection, and publishing or editing releases after CI has passed.

Use when reading status, preparing commits, writing commit messages, comparing local changes, or handling dirty worktrees in this build environment. Focuses on safe non-interactive Git usage, selective staging, and avoiding interference with unrelated user changes.

Library of routines for RISC OS C programming. Provides optimized multiplication/division, processor identification, IRQ control, floating-point preservation, and non-C (registrant) function calls. Use when C code needs assembly-level functionality or when porting code that requires these low-level operations. The library is linked by adding C:Asm.o.libAsm to the LIBS line in a makefile and included via headers like

Guidance for using the GContext graphics library on RISC OS for drawing primitives and rendering text. Use when the agent needs to implement screen output, handle font metrics, or manage graphics contexts.

Use when working with the OSLib typed SWI interface library in the RISC OS build environment, especially to identify which headers, functions, and public types exist for Core, Computer, User, or Toolbox APIs and to translate between SWI names and OSLib wrapper names.

Use the RISC_OSLib library from C-based RISC OS projects, including choosing the correct header include path and linking the exported library object in `Makefile,fe1`. Use when a task adds or reviews `#include "RISC_OSLib/..."` headers, `wimp_*`/other RISC_OSLib APIs, or `LIBS` entries for desktop applications and other RISC_OSLib-based code.

Use the installed Toolbox veneer headers and the public Toolbox manual to create, inspect, and understand RISC OS Toolbox applications, windows, menus, dialogues, and gadget extensions. Use when code includes headers from `/riscos-resources/Export/Lib/tboxlibs/h/`, when a task needs Toolbox object methods/events/types, or when an agent must choose the right calls for SaveAs, Window, Menu, Iconbar, or Toolbox gadget work.

Development notes for the RISC OS AMU makefile build system. Covers the shared makefile types (CModule, CApp, LibraryCommand, LibExport, AsmModule, BasicApp, Documentation, Resource), their variables, build targets, and global configuration. Use when creating or editing Makefile,fe1 files, adding new source files to a build, changing build options, or diagnosing build failures.

Write, review, and debug Perl for the RISC OS build environment, especially scripts that must run under the RISC OS Perl 5.001 interpreter rather than only under a modern host Perl. Use when changing `.pl` or `.pm` files, diagnosing RISC OS Perl parser/runtime failures, or checking whether a Perl construct is too new for the target interpreter.

Development and maintenance of StrongHelp manuals for RISC OS. Use when the agent needs to create, edit, or build StrongHelp manuals, or when processing help pages in the StrongHelp format.

Use when writing, reviewing, or debugging RISC OS Toolbox applications that use the ImageFileGadget object or its methods, including ImageFileGadget_SetValue, SetTransform, SetQuality, SetColourMap, SetScroll, GetBounds, and ImageFileGadget_MouseClick events.

Information about using the riscos-tooltester command, the `tests.txt` file format and replacements that can be used. Use this when the riscos-tooltester command or `testcode/test.pl` is used to manage testing, especially in the Pyromaniac `testcode/` tree.

Write small ARM assembly segments for RISC OS with the ObjAsm toolchain, especially veneers, callbacks, module entry points, and other interface-facing `s/*` code.

Write and test small ObjAsm command-line exercisers under `testcode/s`, including optional reuse of Pyromaniac suites through a build-service runner when a repository needs to ship module tests outside the main Pyromaniac tree.

Coding style and guidance when writing C code. Use whenever C code is being written, read or updated.