Agentics Tooling Monorepo

This repository centralizes reusable agent tooling for development containers and agentic workflows.

It contains related but independently usable parts:

1. a Nix flake that exposes an agent-tools package/profile for ghcr.io/devcontainers/features/nix:1;
2. an agentic setup with repository instructions, reusable skills, prompts, and tool guidance.

The intended outcome is that product repositories can stay small and consume this repository instead of copying long setup scripts into every project.

Repository layout

.
├── AGENTS.md
├── README.md
├── LICENSE
├── .gitignore
├── .github/
│   └── workflows/
│       └── nix-ci.yaml
├── docs/
│   ├── contributing.md
│   ├── versioning.md
│   └── tool-selection.md
├── nix/
│   └── agent-tools/
│       ├── flake.nix
│       ├── README.md
│       └── scripts/
│           ├── update-lock.sh
│           └── validate-tools.sh
├── agentic/
│   ├── README.md
│   ├── tools.md
│   ├── instructions/
│   │   ├── default.md
│   │   ├── devcontainer.md
│   │   ├── nix.md
│   │   └── git.md
│   ├── skills/
│   │   ├── code-review/
│   │   │   └── SKILL.md
│   │   ├── repo-onboarding/
│   │   │   └── SKILL.md
│   │   └── release-notes/
│   │       └── SKILL.md
│   └── prompts/
│       ├── inspect-repo.md
│       └── prepare-change.md
└── examples/
    └── devcontainers/
        └── nix-flake/
            └── devcontainer.json

What each folder is for

AGENTS.md

Root instructions for coding agents working in this repository. Put durable, repository-wide rules here: how to validate changes, how to update lockfiles, how to structure commits, and which directories are generated versus maintained by hand.

Agents should read this before making changes.

.github/workflows/

Automation for validation and publishing.

• nix-ci.yaml validates the flake and tool profile.

docs/

Human-oriented design notes.

• contributing.md explains the local development workflow.
• versioning.md explains how to tag and release the flake and Dev Container Feature parts of the monorepo.
• tool-selection.md explains the criteria for whether a tool belongs in the Nix flake, an official Dev Container Feature, the custom OCI Feature, or project-local setup.

nix/agent-tools/

Reusable Nix flake for agent-focused CLI tools.

This is the recommended default consumption path. A consuming devcontainer can use the official Nix feature and point flakeUri at this subfolder:

{
  "features": {
    "ghcr.io/devcontainers/features/nix:1": {
      "multiUser": true,
      "flakeUri": "github:YOUR_ORG/agentics-tooling?dir=nix/agent-tools#agent-tools",
      "extraNixConfig": "experimental-features = nix-command flakes"
    }
  }
}

The flake intentionally excludes tools that are better installed by official Dev Container Features, such as Go, Java/Gradle, Node, Docker, kubectl/helm/minikube, GitHub CLI, and Nix itself.

agentic/

Agent-facing project context.

• agentic/tools.md describes the CLI tools agents should prefer.
• agentic/instructions/ contains composable instruction files that can be referenced from project-level AGENTS.md files.
• agentic/skills/ contains reusable skills, each with a SKILL.md entrypoint.
• agentic/prompts/ contains copy/paste prompts for common workflows.

examples/

Reference devcontainer configurations.

• examples/devcontainers/nix-flake/devcontainer.json consumes the Nix flake directly through the official Nix feature.
• examples/devcontainers/oci-feature/devcontainer.json consumes the optional published OCI feature.

Recommended consumption model

For most repositories, prefer the Nix flake directly:

{
  "features": {
    "ghcr.io/devcontainers/features/go:1": {},
    "ghcr.io/devcontainers/features/java:1": {
      "version": "21",
      "jdkDistro": "ms",
      "installGradle": true
    },
    "ghcr.io/devcontainers/features/node:2": {},
    "ghcr.io/devcontainers/features/github-cli:1": {},
    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {},
    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
    "ghcr.io/devcontainers/features/nix:1": {
      "multiUser": true,
      "flakeUri": "github:YOUR_ORG/agentics-tooling?dir=nix/agent-tools#agent-tools",
      "extraNixConfig": "experimental-features = nix-command flakes"
    }
  }
}

This keeps official Dev Container Features responsible for language runtimes and platform integrations, while the flake provides the agent-oriented CLI layer.

Updating the Nix lockfile

From the repository root:

cd nix/agent-tools
nix flake update
nix flake check
nix run .#validate

Or use the helper:

./nix/agent-tools/scripts/update-lock.sh

Commit both files when the lock changes:

git add nix/agent-tools/flake.nix nix/agent-tools/flake.lock
git commit -m "Update agent tools flake lock"

Testing the Nix profile locally

cd nix/agent-tools
nix build .#agent-tools
nix run .#validate

To inspect what the profile exposes:

nix path-info -Sh .#agent-tools
ls -la result/bin

Publishing the optional Dev Container Feature

The publishing workflow expects Feature folders under:

devcontainer-features/src/<feature-id>/

Tag releases with a Feature-specific prefix, for example:

git tag devcontainer-features-v0.1.0
git push origin devcontainer-features-v0.1.0

The workflow publishes the features to GitHub Container Registry using devcontainers/action.

Referencing the flake from another repository

Use a stable tag for reproducible onboarding:

"flakeUri": "github:YOUR_ORG/agentics-tooling/v0.1.0?dir=nix/agent-tools#agent-tools"

Use a branch only during active development:

"flakeUri": "github:YOUR_ORG/agentics-tooling/main?dir=nix/agent-tools#agent-tools"

Adding a new tool

1. Check whether an official Dev Container Feature already provides it.

2. Check whether the tool is available in nixpkgs.

3. Add it to nix/agent-tools/flake.nix under the appropriate category.

4. Add the executable name to scripts/validate-tools.sh.

5. Run:

   cd nix/agent-tools
   nix flake update
   nix flake check
   nix run .#validate

6. Update docs/tool-selection.md when the decision needs explanation.

Agentic setup conventions

A consuming project can copy or reference the files under agentic/. A good minimal project setup is:

project/
  AGENTS.md
  agentic/
    tools.md
    instructions/
    skills/

In a consuming project, the root AGENTS.md should point agents at relevant instructions, for example:

Read `agentic/tools.md` before using shell tools. For Nix or devcontainer work, also read `agentic/instructions/nix.md` and `agentic/instructions/devcontainer.md`.

Design principles

• Prefer Nix for reusable CLI tooling.
• Avoid post-create installation for tools that should be available during container setup.
• Keep agent instructions executable: every important rule should say how to verify it.
• Pin through flake.lock; do not pin random versions in shell snippets unless there is no Nix package.