ai-agents-build-and-env

Runbook to recreate the ai-agents dev environment from scratch and survive its traps, including the uv-pinned Python 3.14.6, git hooks install, MCP layer setup, contributor commands, and PEP 668. Use when you say `set up this repo`, `bootstrap the environment`, `fresh clone setup`, or you hit `ModuleNotFoundError yaml`. Do NOT use for the generation pipeline (use `ai-agents-generation-and-release`) or CI gate evidence rules (use `ai-agents-validation-and-qa`).

Zur Installation springen

Repository: rjmurillo/ai-agents
Letzte Quellaktivität: 5. August 2026 um 09:55
Erkannte Sprache von SKILL.md: Englisch
Sterne: 41
Forks: 13

Installationsoptionen

Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.

Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.

Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.

npx skills add https://github.com/rjmurillo/ai-agents --skill ai-agents-build-and-env

Der Befehl bleibt in einer Zeile. Scrollen Sie horizontal, um ihn vor dem Kopieren vollständig zu prüfen.

Sie bevorzugen eine lokale Kopie? Laden Sie die Dateien herunter, die SkillsMP derzeit vorliegen.

Quelldateien prüfen

Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.

Datei-Explorer

2 Dateien

SKILL.md

Quellanweisungen · Schreibgeschützte Vorschau

Zurück zur Suche Zurück zur Installation

spec

Define what to build. Transform a problem into testable requirements with acceptance criteria.

2026-08-09

session-end

Validate and complete session logs before commit. Auto-populates session end evidence (commit SHA, lint results, memory updates) and runs validation. Use when finishing a session, before committing, or when session validation fails. Do NOT use to create a new session log (use session-init) or to repair a session protocol failure reported by CI (use session-log-fixer).

2026-08-09

session-init

Create protocol-compliant JSON session logs with verification-based enforcement. Autonomous operation with auto-incremented session numbers and objective derivation from git state. Use when starting any new session. Use when you say "start a session", "create the session log". Do NOT use for mid-session protocol checks (use session), or to complete and validate a log at the end of a session (use session-end).

2026-08-09

Alle aus diesem Repository ansehen

name	ai-agents-build-and-env
version	1.0.0
description	Runbook to recreate the ai-agents dev environment from scratch and survive its traps, including the uv-pinned Python 3.14.6, git hooks install, MCP layer setup, contributor commands, and PEP 668. Use when you say `set up this repo`, `bootstrap the environment`, `fresh clone setup`, or you hit `ModuleNotFoundError yaml`. Do NOT use for the generation pipeline (use `ai-agents-generation-and-release`) or CI gate evidence rules (use `ai-agents-validation-and-qa`).
license	MIT

ai-agents Build and Environment Runbook

Recreate a working dev environment for this repository from a fresh clone, verify it actually works, and avoid the traps that have cost prior contributors real time. Audience: a zero-context mid-level engineer or Sonnet-class model. Every command below was verified against the repo on 2026-07-03; the Provenance section gives a re-verification one-liner for each volatile fact.

Triggers

set up this repo
bootstrap the environment
fresh clone setup
ModuleNotFoundError: No module named yaml
environment traps

Scope

This skill is environment setup and survival only. Adjacent problems route to siblings:

You want	Use instead

Trap

Symptom

Fix

CONTRIBUTING.md build commands were DEAD before PR #2871

CONTRIBUTING.md:155 said build/Generate-Agents.ps1 PowerShell invocation until PR #2871 repointed it to build/generate_agents.py; zero .ps1 files exist in the repo (ADR-042)

Real commands: uv run python build/generate_agents.py and uv run python build/scripts/build_all.py

PEP 668: bare pip fails

pip install X errors with externally-managed-environment on uv-managed interpreters

Everything goes through uv: uv sync, uv add, uv run (scripts/bootstrap-vm.sh:118-123)

Skill scripts need the project venv

.claude/skills/github/scripts/pr/*.py import github_core, which imports yaml at load; bare python3 throws ModuleNotFoundError: No module named 'yaml' unless .venv/bin is first on PATH (bootstrap-vm.sh arranges that; a manual setup usually does not)

Run skill scripts with uv run python, which resolves the venv deterministically

Moving a worktree leaves the uv shebangs stale

Direct .venv/bin/pytest fails with "bad interpreter" after mv; the shebangs in .venv/bin/* (POSIX) or .venv/Scripts/* (Windows) still name the old worktree path (issue #3170)

Run scripts/maintenance/repair_worktree_venv.py with uv run python (or uv sync --frozen --extra dev --reinstall: --reinstall recreates the launchers a bare --frozen sync would leave stale, --extra dev keeps pytest/ruff/mypy, --frozen matches CI); prefer uv run python -m pytest for move-safe validation

Two floors, not one

pyproject.toml project.requires-python says requires-python = ">=3.14" (the dev/install contract), but plugin hooks run under the host's ambient interpreter, which may be older

Develop and test against .python-version (3.14.6). The blocking CI syntax gate parses every file at the hook-portability floor (3.10), NOT 3.14, so hooks stay portable to older hosts (issue #2655, decoupled from requires-python in issue #3008); see ai-agents-debugging-playbook

LF line endings enforced

CRLF in YAML frontmatter breaks the Copilot CLI parser (github/copilot-cli#694); .gitattributes:59 sets * text=auto eol=lf

Configure your editor for LF; never commit CRLF

Pre-push jobs can take minutes

Lefthook runs the named validators in lefthook.yml for matching push files

Budget minutes per push; do not attempt --no-verify (prohibited, AGENTS.md Never list)

Skill tests not collected by default

uv run pytest tests/ -x skips .claude/skills/*/tests/ (pyproject testpaths are tests, test)

Run skill tests explicitly: uv run pytest .claude/skills/NAME/tests/; details in ai-agents-validation-and-qa

Tool	Floor	Verify
uv	Must resolve the `.python-version` pin (old container uv builds cannot; reinstall via the astral.sh standalone installer, never `uv self update`, which hits GitHub API rate limits on shared egress IPs)	`uv python list "$(cat .python-version)"` prints a row
Python	Exactly the `.python-version` pin, installed by uv	`python3 --version`
Node.js	22 LTS (`NODE_MAJOR=22` in `scripts/bootstrap-vm.sh:40`; AGENTS.md floor says "Node LTS")	`node --version`
PowerShell	7.5.4+ per AGENTS.md Stack. Note: zero `.ps1` files remain in the repo (ADR-042 Python migration), so pwsh is rarely exercised, but the floor is still declared	`pwsh --version`
gh CLI	2.60+ per AGENTS.md Stack	`gh --version`
git, jq, curl	any recent	`git --version`

Server	Transport	Role	When absent
serena	stdio, `uvx --from git+https://github.com/oraios/serena` (port 24282, context claude-code)	Canonical memory (ADR-007) plus LSP symbol navigation	Memories stay readable as plain files under `.serena/memories/` (122 files as of 2026-07-03). The LSP read gate that could misfire on code files was retired in #3216
forgetful	stdio, `uvx forgetful-ai`	Supplementary semantic memory search	ADR-007 fallback: use the Serena `memory-index` memory for keyword discovery. MUST NOT block work or skip memory retrieval because Forgetful is down (ADR-007 "Graceful degradation")
deepwiki	http, `https://mcp.deepwiki.com/mcp`	External GitHub repo documentation	No local impact; fall back to web search

Fact	Source	Re-verify
Python pin 3.14.6	`.python-version`	`cat .python-version`
`requires-python >=3.14` install floor	`pyproject.toml project.requires-python`	`grep -n requires-python pyproject.toml`
Syntax-gate hook floor 3.10 (separate from install floor)	`scripts/validation/validate_python_syntax.py` `_SUPPORT_FLOOR`	`grep -n _SUPPORT_FLOOR scripts/validation/validate_python_syntax.py`
PyYAML 6.0.3 pin	`pyproject.toml project.dependencies`	`grep -n PyYAML pyproject.toml`
`uv sync --frozen --extra dev` is the canonical sync	`scripts/bootstrap-vm.sh:114`	`grep -n "uv sync --frozen" scripts/bootstrap-vm.sh`
Node 22 LTS	`scripts/bootstrap-vm.sh:40`	`grep -n NODE_MAJOR scripts/bootstrap-vm.sh`
pwsh 7.5.4+, gh 2.60+ floors	AGENTS.md Stack section	`grep -n "gh 2.60" AGENTS.md`
Zero .ps1 files (ADR-042)	repo tree	`git ls-files "*.ps1"` prints nothing
Stale pwsh commands	`CONTRIBUTING.md:155,741`	`grep -n pwsh CONTRIBUTING.md`
Git hook jobs, filters, and validators	`lefthook.yml`	`uv run --frozen lefthook validate`
MCP servers serena/deepwiki/forgetful	`.mcp.json`	`cat .mcp.json`
.env key names	`.env.example`	`cat .env.example`
Forgetful fallback table	`ADR-007` (`.agents/architecture/ADR-007-memory-first-architecture.md:108-130`)	`grep -n "Graceful degradation" .agents/architecture/ADR-007-memory-first-architecture.md`
LF enforcement rationale	`.gitattributes:59` and header comments	`grep -n "eol=lf" .gitattributes`
Serena memory file count (122)	`.serena/memories/`	`python3 -c "from pathlib import Path; print(sum(1 for _ in Path('.serena/memories').iterdir()))"`
tests/test_paths.py count (28)	pytest	`uv run pytest tests/test_paths.py --collect-only -q`
uv TLS var rename	uv 0.11.26 runtime warning	`uv run python -c pass` under `UV_NATIVE_TLS`

ai-agents-build-and-env

Installationsoptionen

Quelldateien prüfen

ai-agents Build and Environment Runbook

Triggers

Scope

ai-agents Build and Environment Runbook

Triggers

Scope

Process

Phase 1: Prerequisites

Phase 2: Core Install

Phase 3: Verify the Install

Phase 4: MCP Layer

Phase 5: Editor and LSP Reality

Known Traps

Verification

Anti-Patterns

Provenance and Maintenance

ai-agents-build-and-env

Quellinformationen

Installationsoptionen

Quelldateien prüfen

Mehr aus diesem Repository

ai-agents Build and Environment Runbook

Triggers

Scope

Mehr aus diesem Repository

ai-agents Build and Environment Runbook

Triggers

Scope

Process

Phase 1: Prerequisites

Phase 2: Core Install

Phase 3: Verify the Install

Phase 4: MCP Layer

Phase 5: Editor and LSP Reality

Known Traps

Verification

Anti-Patterns

Provenance and Maintenance