AGENT SKILL

worktree-venv

Provisions a Python venv inside every freshly created worktree — infrastructure only, no agent-side decision logic

License 许可
MIT
所属仓库
muratovv/ai-hats
最近更新
2026-11-05
Stars
★ 3
Forks
1

01 前言 Front Matter

name
worktree-venv
ai_hats
{ "type": "skill", "schema_version": 1 }
license
MIT
description
Provisions a Python venv inside every freshly created worktree — infrastructure only, no agent-side decision logic

02 资源文件 1

03 SKILL.md 正文

worktree-venv

hooks/provision-venv.sh runs after git worktree add and mints a .venv in the new worktree: uv venv, then one editable uv pip install over the root project and every packages/**/pyproject.toml.

Without it the worktree's sys.executable is the main checkout's, whose editable install points at main — so the e2e tier (which strips PYTHONPATH by design) tests the wrong source and the guard blocks the first commit. The paired half is the git-mastery smoke hook preferring <git-toplevel>/.venv/bin/pytest; neither half works alone.

Conventions

  • Warn-continue (ADR-0012 D3/D7). Every declining path exits 0: no root pyproject.toml, .venv/bin/python already present (idempotent), no uv on PATH, or a failed install. Each leaves a worktree without .venv — the status quo before this hook, never worse.
  • Bounded by the 45s wt_in budget; a timeout is a WARN, not a failed create. Cost when it runs: ~1–2s on a warm uv cache.
  • Unpinned by necessity — the repo gitignores uv.lock, so the install resolves fresh and a worktree venv may carry newer dev tools than an older main venv.

References

  • Paired hook: packages/ai-hats-library/src/ai_hats_library/core/skills/git-mastery/git_hooks/pre-commit-smoke.sh
  • Hook contract: docs/how-to-extend.md#worktree-lifecycle-hooks

04 同仓库更多 Skills

muratovv
muratovv/ai-hats

tool-evaluation-protocol

Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.

★ 3
muratovv
muratovv/ai-hats

systematic-debugging

4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.

★ 3
muratovv
muratovv/ai-hats

skill-template

Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

skill-optimization

Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

silent-fallback-gate

PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.

★ 3
muratovv
muratovv/ai-hats

retro-to-framework

Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.

Skill与智能体开发
★ 3