zensical-setup

ra-skills

Agent Skills for the Riksarkivet (Swedish National Archives) rask HTR platform.

ra-skills is the single source of truth for the Claude Code / agent skills shared across Riksarkivet's repos (rask, ra-hcp, lance-audio, …). It exists to stop skills from drifting — before this repo, each project vendored its own copy of writing-python, dagger, fastapi, … under .claude/skills/, and the copies silently diverged. Now every repo consumes the skills from here, so there is one canonical version of each.

The repository follows the standardized Agent Skills format and is modeled on huggingface/skills: each skill is a self-contained folder with a SKILL.md (YAML frontmatter + guidance) and is published as its own granular plugin.

How skills work

A skill is a folder under skills/<name>/ containing a SKILL.md with name + description frontmatter and progressive-disclosure references under references/. Claude Code (in the terminal, VS Code, or Zed) loads the SKILL.md when the description matches your intent.

[!TIP] VS Code and Zed's native agents read the AGENTS.md standard — use the generated agents/AGENTS.md bundle there.

Installation

Claude Code

/plugin marketplace add AI-Riksarkivet/ra-skills
/plugin install <skill-name>@ra-skills

For example:

/plugin install writing-python@ra-skills
/plugin install rask-architecture@ra-skills

VS Code

The Claude Code VS Code extension reads the same marketplace — the /plugin marketplace add + /plugin install commands above apply unchanged. For VS Code's native agents (which read the AGENTS.md standard), drop the generated agents/AGENTS.md bundle into your project root.

Zed

Run Claude Code in Zed via its external-agent (ACP) support — same marketplace commands as above. For Zed's native agent, point it at the generated agents/AGENTS.md bundle.

Scope: ra-skills targets the Claude ecosystem (Claude Code in the terminal, VS Code, and Zed) plus the AGENTS.md standard those editors consume. It deliberately ships no Gemini, Codex, or Cursor manifests.

Skills

Two tiers, distinguished by the rask- name prefix:

• CORE (repo-agnostic) — writing-python, writing-typescript, fastapi, testing-python, python-infrastructure, otel, dagger, dockerfile, turborepo, zensical-setup, zensical-authoring. Reusable in any RA repo (and beyond).
• PROJECT (rask-*, Riksarkivet-coupled) — rask-architecture, rask-services-fleet, rask-htr-pipeline, rask-orchestrator. Encode load-bearing rask knowledge that no single source file states.

Name	Description	Documentation
dagger	Dagger modules/functions in Go for container builds and CI/CD as typed, composable pipelines.	SKILL.md
dockerfile	Production dockerfiles — multi-stage discipline, BuildKit cache mounts, hadolint, the .docker build-context contract.	SKILL.md
fastapi	FastAPI + Pydantic production patterns: async, dependency injection, repositories, services, tests.	SKILL.md
otel	OpenTelemetry for Python services — SDK setup, spans/metrics/logs, semantic conventions, the Collector pipeline.	SKILL.md
python-infrastructure	System-reliability Python: NATS JetStream jobs, Dapr workflows, tenacity retries, Redis cache, OTLP.	SKILL.md
rask-architecture	rask Polylith bricks + the entrypoint/brick composition contract, two-place workspace edits, the make_service_app seam.	SKILL.md
rask-htr-pipeline	The image→ALTO Ray Data/Serve pipeline: GPU-fraction packing math, the OOM-cascade lessons, the fan-out workaround.	SKILL.md
rask-orchestrator	The reconcile→derive→submit loop: single-writer/autostart invariants, end-to-end idempotency, the NATS roadmap.	SKILL.md
rask-services-fleet	Gateway + per-domain services topology: port map, longest-prefix routing, the 502 contract, batches-table ownership.	SKILL.md
testing-python	pytest for the rask suite — importlib import-mode, explicit testpaths, the slow marker, async + respx HTTP mocking.	SKILL.md
turborepo	Turborepo monorepo build system — turbo.json task pipelines, caching/remote cache, --filter/--affected, CI optimization, boundaries.	SKILL.md