Appendix60Appendix Z: AI agent skills

designing-modules

Guidance for designing new RISC OS modules: gathering requirements such as the module name, the SWIs and vectors it needs, and the services it should handle, before any code is written. It is useful when planning a new module's external interface, porting an existing library into module form, or extending an existing module's interface without breaking compatibility for existing callers.

writing-cmodules

Development notes for working with RISC OS modules written in C: project layout, how to build and test a module, and common patterns for SWI implementations, vector claiming, and service-call handlers. It assumes the writing-c skill's fundamentals are already in effect and adds module-specific structure on top. It is useful whenever a module needs creating, a SWI implementing, a vector claiming, or a service handler writing.

using-cmhg

Describes the CMHG file format and the riscos-cmunge tool, which generates the ARM assembly veneers that let modules be written in C or C++ rather than hand-written assembly, across 26-bit, 32-bit, and 64-bit architectures. It is useful whenever a module's CMHG header needs creating or editing, including its entry-point declarations, SWI tables, and vector or service-handler chunks.

writing-oslib-defs

Covers OSLib Def files: the compact, declarative interface descriptions from which riscos-defmod generates C headers, ObjAsm veneers, assembler and C SWI headers, SrcEdit help, and StrongHelp content. It is useful when an interface needs documenting once and then built consistently into several output forms, since the Def file is the source of truth and everything else is a generated artefact derived from it.

allocating-resources

Guidance for registering RISC OS allocations, such as module names, SWI chunks, error blocks, Commands, filetypes, and system variables, with the RISC OS Open allocation service, including the preferred !Allocate desktop application and the allocation email address. It is useful any time new code claims a resource that must not clash with other RISC OS software.

writing-c

Coding style and project-structure guidance for C code in the build environment, including the source and header directory conventions and other house-style rules used throughout this manual's examples. It is the foundational skill for nearly all C work here, and is a stated prerequisite for the module and porting skills above.

writing-cplusplus

Guidance for writing, building, and testing C++ for the 64-bit RISC OS build environment, including project layout under cc/ and h/, riscos64-c++, riscos-project --type c++command, the ${C++LIB} library variable, and interop between C++ and C or RISC OS APIs. It is useful for any C++ command-line project, since C++ is currently only supported on the 64-bit toolchain.

writing-fortran

Covers Fortran development in the build environment. The skill is split into focused reference areas read only as needed:

• building with riscos64-fortran, source layout, and modules;
• interworking with C, including _kernel_swi_regs and C/control-terminated strings;
• generating Fortran modules from RISC OS header constants.

It is useful whenever Fortran source needs writing, reviewing, building, or interfacing with C.

writing-pascal

Covers Pascal development in the build environment: translating Pascal to C with riscos-p2cc/riscos64-p2cc, source layout under p/, direct and project builds for both 32-bit and 64-bit RISC OS with riscos-project --type pcommand, and toolchain quirks such as the mandatory architecture switch and the 32-bit-only limitation on printing real values directly. It is useful whenever Pascal source needs writing, reviewing, or building, and notes that multi-file Pascal builds and Pascal/C interop remain unverified in this environment.

using-bbcbasic

Syntax and usage notes for BBC BASIC on RISC OS, covering the textual (,fd1) and tokenised (,ffb) program formats, detokenising tokenised files with riscos-basicdetokenise, and other BASIC-specific conventions such as line-numbering and error-handling idioms. It is useful whenever BASIC source is created, edited, or reviewed.

writing-assembly

Procedures, standards, and pitfalls for writing small, interface-facing ARM assembly fragments with riscos-objasm and riscos-link: veneers, callbacks, module entry points, and similar s/* code. It is useful for the kind of hand-written assembly that sits at a module or application boundary, rather than for writing a whole program in assembly.

writing-assembly-tests

Covers writing and testing small ObjAsm command-line exercisers under testcode/s, including reusing Pyromaniac test suites through a build-service runner when a repository ships module tests outside the main Pyromaniac tree. It is useful when a module or SWI needs a minimal assembly-level test harness rather than a full Pyromaniac integration test.

porting-to-riscos-c

A workflow for turning an existing C repository into a RISC OS buildable port using riscos-cport, RISC OS makefiles, and Norcroft/RISC OS build validation: detecting the project's real entry points, generating Makefile,fe1 files, and repairing source for the RISC OS toolchain. It is useful as the starting point whenever a non-RISC OS C project needs to be brought into the build environment, letting riscos-cport do the first pass before manual repair.

writing-pymodules

Describes how to build and test PyModules, the Python modules that implement RISC OS modules under RISC OS Pyromaniac, including loading and exercising a PyModule with riscos-run. It is useful when a module's behaviour needs prototyping, testing, or reimplementing against the Pyromaniac runtime, rather than only against real ARM code.

writing-pyromaniac-integration-tests

Covers creating or updating integration tests in the Pyromaniac repository, especially testcode/tests-*.txt suites, expectation files under testcode/expect/, BASIC smoke tests in testcode/basic/, and assembly exercisers in testcode/s/. It is useful when a Pyromaniac feature needs wiring into the existing integration test harness with the smallest practical test surface.

ci-testing

Covers creating, extending, reviewing, and repairing RISC OS continuous integration 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. It is useful when a repository's automated build and test pipeline needs creating or updating in a way that matches its real RISC OS build, test, and packaging shape.

using-makefiles

Development notes for the RISC OS AMU makefile system used by riscos-amu: the shared makefile types (CModule, CApp, LibraryCommand, LibExport, AsmModule, BasicApp, Documentation, Resource), their variables, build targets, and global configuration. It is useful whenever a Makefile,fe1 is created or edited, a new source file is added to a build, build options change, or a build fails and needs diagnosing.

writing-prminxml

Covers the PRM-in-XML format and the riscos-prminxml tool used to create, lint, and build manual-style API and interface documentation, including this manual itself. It is useful whenever interface or external documentation needs writing in the Programmer's Reference Manual style, covering SWI, service call, system variable, and command definitions.

using-stronghelp

Development and maintenance notes for StrongHelp manuals, the standard RISC OS hypertext help format, including extracting, listing, and rebuilding manual pages with riscos-shextract and riscos-strongcopy. It is useful whenever StrongHelp manuals need creating, editing, or processing.

using-tooltester

Covers scripted integration testing of RISC OS command-line tools using riscos-tooltester and the testcode/test.pl runner, including the tests.txt file format and the output replacements it supports. Tests run a tool via riscos-build-run, capture its output, and compare it against expectation files under testcode/expect/. It is useful whenever scripted tool invocation tests need running, interpreting, or extending; a Pyromaniac runtime is not required for this testing approach.

using-perl

Writing, reviewing, and debugging Perl scripts for the RISC OS build environment, particularly scripts that must run under the RISC OS Perl 5.001 interpreter (used inside riscos-build-run environments) rather than only under a modern host Perl. It covers compatibility constraints, Perl 5.001-safe constructs, and how to confirm behaviour by running the script via riscos-build-run. It is useful when changing .pl or .pm files, diagnosing RISC OS Perl failures, or checking whether a Perl construct is too new for the target interpreter.

updating-robe-skills

Explains how to create or update AI skills for this build environment without editing the installed /etc/agentskills copies directly, using the ai skills new and ai skills show workflow (the singular ai skill new/ai skill show is also accepted, since these operations act on one named skill at a time; both forms run the same code) to work safely in a project- or user-controlled skill location such as ~/.config/ai/skills. It is useful whenever a user wants a new skill, or a locally modified copy of a shipped one, without touching the shipped skill set that other users of the environment share.

riscos-wimp

Covers Wimp-facing code in applications and modules. The areas it helps with include:

• task initialisation and shutdown, and template loading;
• window creation, opening, and the redraw/open/close event flow;
• icon bar icons and icon state changes;
• mouse and key handling, menus, and help messages;
• Wimp data structures and SWIs in general;
• module-specific Wimp integration, such as Service_StartWimp, Desktop_ commands, or task lifecycle handling inside a module.

It is useful for almost any desktop-facing application or module work.

riscos-wimp-app

Builds on riscos-wimp with guidance on structuring and packaging small desktop Wimp applications, especially icon bar applications, without repeating the raw Wimp protocol details. It is useful when creating or restructuring a desktop application with Wimp startup, poll-loop dispatch, icon bar icons, packaged Resources files, or application naming changes.

riscos-style

Applies the official Acorn RISC OS Style Guide when designing, reviewing, or implementing desktop applications, covering startup and shutdown, windows, menus, dialogue boxes, icons, colour, sound, input handling, selection, and application structure. It is useful when code or UI needs checking against classic RISC OS desktop behaviour rather than against arbitrary modern taste.

riscos-wimp-templates

Covers creating or updating Wimp template descriptions as TemplateText files using riscos-ccres, including choosing bundled window assets, following standard RISC OS dialogue patterns, and assembling the required wimp_window blocks into a template file. It is useful when an application needs a new or revised template-based window definition rather than hand-built runtime window structures.

riscos-output

Covers the RISC OS output system beyond plain text output. It distinguishes several kinds of output that are often confused:

• VDU output: character and control codes that position and colour text, output through OS_WriteC, OS_WriteN, and OS_Write0;
• graphics output: OS_Plot operations that draw lines, circles, and simple shapes;
• sprite, Draw file, and font rendering;
• palette programming and ColourTrans translation tables;
• ImageFileRender-based rendering of arbitrary image formats.

It is useful whenever code draws to the screen or another output device, rather than simply writing text; it is not needed for plain textual output.

riscos-graphics-converters

Covers creating or updating ImageFileConvert converter modules: registering source-to-destination filetype pairs, implementing the Convert and MiscOp entry points, emitting Sprite or sprite-file output, and handling ImageFileConvert service startup and shutdown. It is useful when adding support for a new image format, or when calling ImageFileConvert SWIs directly to convert image buffers and files.

using-libtoolbox

Covers the installed Toolbox veneer headers under /riscos-resources/Export/Lib/tboxlibs/h/, and the public Toolbox object module API: application startup, object lifecycle, event flow, resource files, and the standard object classes including Window, Menu, Iconbar, SaveAs, and the common gadget types. It is useful whenever code includes Toolbox headers, implements Toolbox object methods or event handlers, or a task needs guidance on which SWIs and callback patterns to use for a given Toolbox object class.

using-toolbox-imagefilegadget

Covers the Toolbox ImageFileGadget object, which displays image files in a Toolbox window by supplying file bytes and metadata to ImageFileRender for the actual redraw, including SetValue, SetTransform, SetQuality, SetColourMap, SetScroll, GetBounds, and mouse-click events. It is useful for Toolbox applications that need to display images, as distinct from implementing a new image renderer or converter.

using-libgcontext

Guidance for the GContext graphics library, which provides an abstracted interface for 2D drawing primitives and text rendering through a gcontext_t graphics context. It is useful when implementing screen output, handling font metrics, or managing graphics contexts at a higher level than raw OS_Plot calls.

using-libriscoslib

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

riscos-desktop-fileraction

Covers starting interactive desktop Filer operations, such as copy, move, delete, access, set type, count, stamp, copy-local, or find, through the FilerSWIs/FilerAction module, by sending FilerAction_SendSelectedDirectory, FilerAction_SendSelectedFile, and FilerAction_SendStartOperation in the correct order. It is useful when an application should open a Filer action window for the user to see and control, rather than perform the filesystem change silently itself.

riscos-filer-like

Covers creating, reviewing, or extending a Filer-style object browser in a Wimp window: a selectable grid or list of objects with redraw-on-demand, alternate view formats, hit-testing, scrolling, and resize behaviour driven from object geometry. It separates the object model, geometry model, and Wimp shell so redraw, layout, and selection state do not drift apart. It is useful for file browsers, media browsers, pickers, launchers, and similar desktop views modelled on the Filer without needing to implement the real desktop Filer protocol.

riscos-network-resolver

Explains the RISC OS Resolver module: DNS lookups, SWIs, commands, configuration variables, cache control, service calls, and the returned hostent data. It is written to stand alone even when the original source tree is not available. It is useful whenever code needs shared host name or address resolution, or whenever Resolver's own behaviour needs implementing, reviewing, or documenting.

riscos-network-dcistatistics

Covers the generic DCI4 statistics interface: how suppliers enumerate themselves, how gatherers describe and read statistics, the provider and description structures, and Service_StatisticEnumerate. It is useful when implementing a statistics supplier in a module or driver, or writing or reviewing a statistics gatherer, as distinct from working with one module's own private counters.

riscos-urls-fetching

Covers fetching URL or URI contents using the Acorn URL_Fetcher module: URL_Register, URL_GetURL, URL_Status, URL_ReadData, URL_Stop, URL_Deregister, URL_ParseURL, proxy setup, and protocol enumeration. It is useful when code needs to retrieve the contents of an HTTP, HTTPS, FTP, or similar URL, as distinct from launching one in the desktop.

riscos-urls-launching

Covers launching URLs or URIs from code, Obey files, commands, desktop applications, Wimp tasks, or modules, using the AcornURI handler, URI_Dispatch, *URIdispatch, the URI filetype &F91, and the legacy ANT URL broadcast mechanism. It is useful whenever a user-facing action should open a URL in the user's configured handler, rather than hard-coding a particular browser.

using-liboslib

Covers the OSLib typed SWI interface library, exported under /riscos-resources/Export/Lib/OSLib, which provides type-safe C wrappers for the complete RISC OS API. It covers the library layout, how to map between PRM SWI names and OSLib C wrapper names, and which header families exist for Core, Computer, User, and Toolbox APIs. It is useful when code depends on OSLib headers, when a SWI call needs a type-safe veneer, or when translating between raw SWI numbers and named OSLib functions.

using-libasm

Covers libasm, a C-callable library of optimised assembly routines, linked via C:Asm.o.libAsm. Its categories of functionality include:

• multiplication and division using 64-bit intermediate arithmetic to avoid overflow;
• processor identification;
• IRQ control;
• floating-point state preservation;
• non-C (registrant) function calls.

It is useful when C code needs assembly-level performance or low-level operations, or when porting code that already depends on this kind of routine.

riscos-throwback

Explains Throwback, the DDEUtils protocol that command-line tools and taskwindow programs use to report warnings, errors, and informational diagnostics to a desktop editor, via DDEUtils_ThrowbackStart, DDEUtils_ThrowbackSend, DDEUtils_ThrowbackEnd, and DDEUtils_ThrowbackRegister. It is useful when adding, reviewing, or debugging diagnostic reporting from a compiler, taskwindow program, or other build-time tool, so a desktop editor can let the user click through to the affected source line.

riscos-filesystem

Explains RISC OS filename conventions and how to interact with the filesystem correctly: directory separators, filetype encoding, and other conventions that differ from POSIX systems. See Naming conventions and project files for the equivalent reader-facing reference material. The skill is useful whenever code reads, writes, or otherwise manipulates RISC OS-style filenames and paths, especially when porting code written against POSIX assumptions.

riscos-commands

A reference for the Commands used at the RISC OS command line, in Command files (for *Exec), Obey files, BASIC's OSCLI, --command arguments to riscos-build-run, and .robuild.yaml or Pyromaniac --commands execution. It covers areas such as:

• conditionals, using *IF and *IfThere;
• variable handling, using *Set, *SetEval, and similar commands;
• filesystem operations such as *Copy, *Delete, and *Dir, including filing-system-specific configuration.

It is useful whenever a script, Obey file, or test needs a specific *Command's exact syntax.

riscos-re

A guide to analysing RISC OS module binaries and reconstructing their functionality, interfaces, and internal state machines, starting from the module header and working outward with riscos-dump and riscos-dumpi. It is useful when an existing module's behaviour needs understanding or reimplementing in C without the original source.

reading-assembly

Covers reading and translating RISC OS ObjAsm/ARM assembly into another language, a PyModule, tests, or interface documentation, starting from the public module surface (header, exported SWI names table, command table, service table, and error blocks) rather than from implementation comments. It is useful when converting s/* assembler modules, reconstructing SWI behaviour, validating comments against generated tables or disassembly, or proving binary-compatible data layout and boundary behaviour.

using-git

Covers safe, non-interactive Git usage in the build environment: reading status, preparing commits, writing commit messages, comparing local changes, and handling a dirty worktree without disturbing unrelated changes, including avoiding broad staging commands such as git add .. It is useful for almost any task that ends in a commit.

using-gh

Covers GitHub-side operations through the gh command: authentication checks, pull requests, Actions run inspection, release inspection, and publishing or editing releases once CI has passed. It is useful alongside using-git when a task needs to reach GitHub itself, rather than only the local repository.

creating-pull-requests

Covers writing reviewer-focused pull request or merge request descriptions: confirming the target branch, gathering the real testing performed, deciding whether the change should be a draft, and structuring the body around summary, concrete changes, and testing. It is useful when the repository work is complete locally and the next step is to present it clearly for review.