AGENT SKILL

repo-init

Initialize a repository with devenv, direnv, and jj (Jujutsu). Use when setting up a new project, initializing a repo, or when the user mentions devenv, direnv, or jj setup together.

License 许可
GPL-2.0
所属仓库
vjrasane/dotfiles
最近更新
2026-11-05
Stars
★ 0
Forks
0

01 前言 Front Matter

name
repo-init
description
Initialize a repository with devenv, direnv, and jj (Jujutsu). Use when setting up a new project, initializing a repo, or when the user mentions devenv, direnv, or jj setup together.
argument-hint
[ "project directory" ]

02 资源文件 1

03 SKILL.md 正文

Repo Init

Bootstrap a repository with the standard development tooling: devenv, direnv, and jj.

Instructions

Step 1: Determine the target directory

  • If the user provides a directory, use it
  • If a directory name is given but doesn't exist, create it
  • Otherwise use the current working directory
  • Confirm the directory is correct before proceeding

Step 2: Initialize jj (Jujutsu)

Initialize a colocated jj repository. Colocated mode keeps a .git directory alongside .jj so that tools expecting git still work.

cd <target-dir>
jj git init --colocate

If the directory already has a .git repo but no .jj:

jj git init --colocate

If .jj already exists, skip this step.

After initializing, ask the user what the main/trunk branch name is (usually main), then configure the trunk revset alias in .jj/repo/config.toml:

#:schema https://docs.jj-vcs.dev/latest/config-schema.json

[revset-aliases]
"trunk()" = "main@origin"

Replace main with the actual trunk branch name if different.

Step 3: Set up devenv

Create a devenv.nix file if one doesn't exist:

{
  pkgs,
  config,
  ...
}:
{
  packages = with pkgs; [
    just
  ];

  claude.code.enable = true;

  claude.code.mcpServers = {
    devenv = {
      type = "stdio";
      command = "devenv";
      args = [ "mcp" ];
      env = {
        DEVENV_ROOT = config.devenv.root;
      };
    };
  };
}
  • claude.code.enable = true generates the project .mcp.json automatically
  • The devenv MCP server exposes search_packages and search_options tools so agents can search nixpkgs and devenv options when editing devenv.nix
  • config must be in the function arguments to reference config.devenv.root

Always include just — it is the standard task runner for all projects.

Also create a justfile in the project root if one doesn't exist:

default:
    @just --list

This gives a useful default that lists all available recipes. The user will add project-specific recipes as needed.

Create a devenv.yaml file if one doesn't exist:

# yaml-language-server: $schema=https://devenv.sh/devenv.schema.json
inputs:
  nixpkgs:
    url: github:cachix/devenv-nixpkgs/rolling

If the user wants git-hooks via devenv, add the git-hooks input:

  git-hooks:
    url: github:cachix/git-hooks.nix
    inputs:
      nixpkgs:
        follows: nixpkgs

Step 4: Set up direnv

Create a .envrc file if one doesn't exist:

# shellcheck shell=bash
source_up_if_exists

eval "$(devenv direnvrc)"

use devenv

watch_file .env
dotenv_if_exists .env
  • source_up_if_exists inherits parent .envrc files (useful for nested projects)
  • watch_file .env and dotenv_if_exists .env load environment variables from .env and reload when it changes

Then allow it:

direnv allow

Step 5: Update .gitignore

If a .gitignore exists, merge these entries into it. If it doesn't exist, create one. Group entries under comments and preserve any existing content.

These entries MUST be present:

# Devenv
.devenv*
devenv.local.nix
devenv.local.yaml

# direnv
.direnv

# pre-commit
.pre-commit-config.yaml

# Environment
.env

# Claude
.claude/
.mcp.json
  • .devenv* covers .devenv/ (the devenv state directory) and .devenv.flake.nix (auto-generated flake)
  • devenv.local.nix and devenv.local.yaml are machine-specific overrides that shouldn't be committed
  • .pre-commit-config.yaml is auto-generated by devenv's git-hooks feature
  • .claude/ contains local agent state and settings that are per-user
  • .mcp.json is auto-generated by claude.code.enable in devenv

Step 6: Create AGENTS.md

Create a AGENTS.md file in the project root with agent instructions. If one already exists, merge these rules into it rather than overwriting.

The AGENTS.md MUST contain the following sections (adapt wording to fit existing content if merging):

## Development Environment

This project uses **devenv** to manage development tools and dependencies. The environment activates automatically via direnv when you enter the project directory.

- Install CLI tools and system-level dependencies via `devenv.nix` (under `packages`)
- Do NOT use devenv for language-specific libraries — use the project's native package manager instead (npm, uv, pip, cargo, go modules, etc.)
- To add a new tool: edit `devenv.nix`, then let direnv reload or run `devenv shell`

## Version Control

This project uses **jj (Jujutsu)** for version control with git colocated mode. NEVER use git commands unless absolutely necessary (e.g., a tool has no jj support, or jj lacks the needed functionality). If you must use git, explain why.

jj quick reference:
- `jj new` — start new work on top of current change
- `jj describe -m "message"` — describe the current change
- `jj commit -m "message"` — snapshot working copy and start a new change
- `jj log` — view change history
- `jj diff` — view uncommitted changes
- `jj bookmark create <name>` — create a bookmark (branch equivalent)
- `jj git fetch` — fetch from remote
- `jj git push` — push to remote

Do NOT use `git add`, `git commit`, `git push`, `git pull`, `git checkout`, `git switch`, `git branch`, or any other git porcelain command.

## MCP Servers

MCP servers for this project are managed through devenv. Add servers to `claude.code.mcpServers` in `devenv.nix` — devenv generates the `.mcp.json` file automatically. Use `/add-mcp` to add common servers.

Step 7: Create .claude/settings.json (optional)

If the project doesn't have a .claude/settings.json, ask the user if they want to create one. This can include project-specific permissions or MCP server settings.

Step 8: Verify the setup

Run these checks:

  1. jj status works and shows the repo state
  2. devenv shell -- echo "devenv works" succeeds (or direnv has activated)
  3. AGENTS.md exists with the correct content
  4. .envrc exists and is allowed

Report the results to the user.

Guidelines

  • Never overwrite existing files without asking — always check first and merge if needed
  • If jj is not installed, tell the user to add it to their global home.nix or install it
  • If devenv is not installed, tell the user to install it (it should be in their global home.nix)
  • If direnv is not installed, tell the user to add it to their global home.nix
  • Keep the generated devenv.nix minimal — don't add packages the user hasn't asked for
  • The AGENTS.md content is the most important part — it ensures all future agent sessions respect the tooling choices

04 同仓库更多 Skills