Alastri skills and context

Out of the box, an agent knows nothing about our codebase. It doesn’t know that build.ps1 exists, that dotnet build won’t link the native mesh code, or where the shared WinForms controls live. It rediscovers all of that — slowly, and sometimes wrongly — at the start of every session.

The Alastri agent config repo fixes that. It’s a small set of files you drop into your source checkout: a CLAUDE.md that orients the agent, progressively-discoverable docs for each app, a build/test script, and a handful of team skills. Once it’s in place, every session starts with the same shared context instead of a blank slate.

Clone and install

1. Clone the repo:

   git clone https://per-srv-git01.micromine.com/alastri/agentskills.git

2. Copy its contents into the root of your Alastri source checkout, so CLAUDE.md, docs/, build.ps1, and .claude/ sit alongside the code:

   Copy-Item -Path .\agentskills\* -Destination C:\source\Alastri\ -Recurse

3. Start claude from the source root. It reads CLAUDE.md automatically on launch.

Note

The files layer on top of the Alastri source repo rather than living inside it, so the agent config can version independently. Pull the skills repo periodically to pick up updates.

What’s in the repo

• CLAUDE.md the context the agent reads first
• build.ps1 build & test wrapper
• Directorydocs/

  • common-patterns.md shared app shell, controls, helpers
  • Directoryapplications/ one reference per app (Hub, APS, ATS, HI, RR, SC)

    • …
  • Directorycommon/ deep dives on shared controls

    • …
• Directory.claude/

  • Directoryskills/ team workflows the agent can invoke

    • …

CLAUDE.md

The agent reads CLAUDE.md at the start of every session, so it holds the facts that apply everywhere. Keeping it short is important — everything in it is loaded into context before the agent has done anything, so it earns its place by steering the agent away from common mistakes.

Codebase guide

The guide lists the docs under docs/ and tells the agent to read the relevant one when a task touches that area, rather than loading them all up front. Each app and each shared subsystem gets its own reference, so the agent can pull in detail on demand.

The guide does two things. First, it gives the agent a quick map of the monorepo: the main folders and files that matter for each application, plus the shared subsystems under common/. The agent knows where the Hub code lives versus ATS, and what each area is for, without having to crawl the tree to find out.

Second, that map heads off a common failure mode. Without knowing what already exists, an agent writes a throwaway helper for something the codebase already has. Pointing it at the common-patterns reference — the wizard system, the viewport, treelist helpers, the Geometry IO helpers — means it reuses the shared building blocks instead of reinventing them.

Technologies

A short, high-level list of what the code is built on — .NET Framework 4.8, WinForms with DevExpress controls, an OpenGL viewport. The agent can infer some of this from the files, but stating it up front avoids wrong guesses (for example, reaching for web-stack or .NET-Core-only patterns that don’t apply here).

Building and testing

This section points the agent at build.ps1 and tells it what not to do:

./build.ps1 -List          # list the products you can build/test
./build.ps1 Hub            # build a product's program
./build.ps1 Hub -Test      # build + run that product's tests
./build.ps1 -All -Test     # build + run tests for every product

We added the script because agents consistently struggled to build these projects on their own. They’d reach for dotnet build or try to build a single .csproj, and the build would fail — these are .NET Framework projects that need full Visual Studio MSBuild, and the native Alastri.Mesh dependency only links when the build goes through the solution. The agent would then burn time guessing at MSBuild paths and platform flags.

build.ps1 locates MSBuild via vswhere, builds through Alastri.sln with the right platform mapping, and exposes a simple per-product interface. The CLAUDE.md note steers the agent straight to it, so building and running tests becomes a one-liner.

Skills

The .claude/skills/ folder ships team skills: short instruction files that package a repeatable task so the agent runs it the same way every time. Invoke one by typing / followed by its name. Because they live in the repo, the whole team shares the same workflows, and improvements land for everyone on the next pull.

For what the bundled skills do and how they fit together, see the workflow introduction.

Improving the skills and context

When you see the agent struggle with a task — a wrong build command, a missed existing helper, a misunderstood convention — ask it at the end of the session to reflect on what would have helped it avoid the problem. Its answer is often a precise suggestion: a fact that belongs in CLAUDE.md, a missing entry in the codebase guide, or a rough edge in a skill.

That reflection is one of the best sources of improvements to this repo. When it surfaces something useful, fold it back in and open a change against the skills repo so the rest of the team benefits.