App-Building Instructions

This repository contains reusable AI assistant instructions that document how I prefer to build applications. They are written in a skill-style folder format that is best supported by Codex, but the SKILL.md files can also be read or referenced by Claude or any assistant that can use project instruction files.

Each instruction pack is a folder with a SKILL.md file. Some folders also include optional agents/openai.yaml metadata for tools that understand it.

Available Instruction Packs

Skill	Use it for
build-my-apps	General app-building defaults across stacks: Rust backends, Angular frontends, Tailwind styling, Docker, Temporal, PostgreSQL, releases, CI, docs, event logging, testing, and operational conventions.
build-rust-apps	Rust backend apps: routes/services/libs/models structure, Axum-style APIs, Toasty CLI migrations, DTO boundaries, request event logs, observability, and Docker-backed tests.
build-typescript-apps	Standalone Fastify TypeScript apps: Bun by default, strict TypeScript, Biome, route/service/lib/model boundaries, validation, OpenAPI, and typed errors.
build-python-apps	Python services: uv, Ruff, Pyright, pytest, typed code, src layout, service-layer business logic, and configuration defaults.
build-django-apps	Django/DRF services: Pydantic settings, PostgreSQL, dj_database_url, no viewsets, service-oriented APIs, WhiteNoise, Cloudflare R2, Docker, and typed Python.
build-microservices	Microservice architecture: service manifests, permission contracts, service registration, generated clients, frontend manifests, auth boundaries, and service documentation.

How To Use

Use these instructions by pointing your assistant at the relevant folder or by referencing the instruction pack name in your prompt.

Examples:

Use the build-my-apps instructions to scaffold this product.
Use the build-rust-apps instructions while refactoring this backend.
Use the build-django-apps instructions to design this DRF service.
Use the build-microservices instructions to add service-to-service auth and manifests.

For assistants that support $skill-name syntax, you can also reference them explicitly:

Use $build-my-apps to scaffold this product.

Explicit references are useful when you want a particular convention applied.

Repository Layout

build-my-apps/
  SKILL.md
  agents/openai.yaml
build-rust-apps/
  SKILL.md
  agents/openai.yaml
...

SKILL.md is the source of truth for an instruction pack. agents/openai.yaml contains optional UI metadata for tools that support it.

Installing Locally

To copy these instruction packs into a local assistant configuration directory, run the installer:

./scripts/install-skills.sh

The script prompts for an install destination. Codex skills are the recommended/default target. For Claude or another assistant, choose the directory that tool reads custom instructions from; manual references from that assistant's project instructions may still be needed.

If you are working directly from this repo, you can point your assistant at the relevant folder path explicitly in the prompt.

Maintaining Instruction Packs

When editing or adding an instruction pack:

1. Keep the folder name and name frontmatter identical.
2. Keep frontmatter limited to name and description.
3. Put core guidance in SKILL.md; add references or scripts only when they are genuinely needed.
4. Keep agents/openai.yaml aligned when present.
5. Validate the folder format after changes when using a compatible validator.

Codex-compatible validation:

python3 /Users/lordsarcastic/.codex/skills/.system/skill-creator/scripts/quick_validate.py ./build-my-apps

If your local Python does not have PyYAML, run validation from a temporary environment or another Python environment with PyYAML installed.