Repository Guidelines

- **Do** match the interpreter requirement declared in `pyproject.toml` (Python ≥ 3.12) and install `requirements.txt` plus `requirements-dev.txt` before running tools.

0 views

Feb 1, 2026

Time

5 min

Difficulty

Beginner

Type

prompt

Package

Single file

Loading actions...

Contents

Skill content

Main instructions and any bundled files for this skill.

markdown

Repository Guidelines

Dos and Don’ts

Do match the interpreter requirement declared in pyproject.toml (Python ≥ 3.12) and install requirements.txt plus requirements-dev.txt before running tools.
Do run tests with PYTHONPATH=. set to keep imports functional (for example PYTHONPATH=. ./.venv/bin/pytest tests/unittest/test_fix_json_escape_char.py -q).
Do adjust configuration through .pr_agent.toml or files under pr_agent/settings/ instead of hard-coding values.
Don’t commit secrets or access tokens; rely on environment variables as shown in the health and e2e tests.
Don’t reformat or reorder files globally; match existing 120-character lines, import ordering, and docstring style.
Don’t delete or rename configuration, prompt, or workflow files without maintainer approval.

Project Structure and Module Organization

PR-Agent automates AI-assisted reviews for pull requests across multiple git providers.

pr_agent/agent/ orchestrates commands (review, describe, improve, etc.) via pr_agent/agent/pr_agent.py.
pr_agent/tools/ implements individual capabilities such as reviewers, code suggestions, docs updates, and label generation.
pr_agent/git_providers/ and pr_agent/identity_providers/ handle integrations with GitHub, GitLab, Bitbucket, Azure DevOps, and secrets.
pr_agent/settings/ stores Dynaconf defaults (prompts, configuration templates, ignore lists) respected at runtime; .pr_agent.toml overrides repository-level behavior.
tests/unittest/, tests/e2e_tests/, and tests/health_test/ contain pytest-based unit, end-to-end, and smoke checks.
docs/ holds the MkDocs site (docs/mkdocs.yml plus content under docs/docs/); overrides live in docs/overrides/.
.github/workflows/ defines CI pipelines for unit tests, coverage, docs deployment, pre-commit, and PR-agent self-review.
docker/ and the root Dockerfiles provide build targets for services (github_app, gitlab_webhook, etc.) and the test stage used in CI.

Build, Test, and Development Commands

Create or activate a virtual environment, then install runtime dependencies with pip install -r requirements.txt; add development tooling via pip install -r requirements-dev.txt.
Run a single unit test (verified): PYTHONPATH=. ./.venv/bin/pytest tests/unittest/test_fix_json_escape_char.py -q.
Run the full unit suite: PYTHONPATH=. ./.venv/bin/pytest tests/unittest -v.
Execute the CLI locally once dependencies and API keys are available: python -m pr_agent.cli --pr_url <https://host/org/repo/pull/123> review.
Build the test Docker target mirror of CI when containerizing: docker build -f docker/Dockerfile --target test . (loads dev dependencies and copies tests/).
Generate and deploy documentation with MkDocs after installing the same extras as CI (mkdocs-material, mkdocs-glightbox): mkdocs serve -f docs/mkdocs.yml for previews and mkdocs gh-deploy -f docs/mkdocs.yml for publication.

Coding Style and Naming Conventions

Python sources follow the Ruff configuration in pyproject.toml (line-length = 120, Pyflakes plus flake8-bugbear checks, and isort ordering). Keep imports grouped as isort would produce and prefer double quotes for strings.
Pre-commit (.pre-commit-config.yaml) enforces trailing whitespace cleanup, final newlines, TOML/YAML validity, and optional isort; run pre-commit run --all-files before submitting patches if installed.
Match existing docstring and comment style—concise English comments using imperative phrasing only where necessary.
Configuration files in pr_agent/settings/ are TOML; preserve formatting, section order, and comments when editing prompts or defaults.
Markdown in docs/ uses MkDocs conventions (YAML front matter absent; rely on heading hierarchy already in place).

Testing Guidelines

Pytest is the standard framework; keep new tests under the closest matching directory (tests/unittest/ for unit logic, tests/e2e_tests/ for integration flows, tests/health_test/ for smoke coverage).
Prefer focused unit tests that isolate helpers in pr_agent/algo/, pr_agent/tools/, or provider adapters; use parameterized tests where existing files already do so.
Set PYTHONPATH=. when invoking pytest from the repository root to avoid import errors.
End-to-end suites require provider tokens (TOKEN_GITHUB, TOKEN_GITLAB, BITBUCKET_USERNAME, BITBUCKET_PASSWORD) and may take several minutes; run them only when credentials and sandboxes are configured.
The health test (tests/health_test/main.py) exercises /describe, /review, and /improve; update expected artifacts if prompts change meaningfully.

Commit and Pull Request Guidelines

Follow CONTRIBUTING.md: keep changes focused, add or update tests, and use Conventional Commit-style messages (e.g., fix: handle missing repo settings gracefully).
Target branch names follow feature/<name> or fix/<issue> patterns for substantial work.
Reference related issues and update README or docs when user-facing behavior shifts.
Ensure CI workflows (build-and-test, code-coverage, docs-ci) succeed locally or in draft PRs before requesting review; reproduce failures with the documented commands above.
Include screenshots or terminal captures when modifying user-visible output or documentation previews.

Safety and Permissions

Ask for confirmation before adding dependencies, renaming files, or changing workflow definitions; many consumers embed these paths and prompts.
Stay within existing formatting and directory conventions—avoid mass refactors, re-sorting of prompts, or reformatting Markdown beyond the touched sections.
You may read files, list directories, and run targeted lint/test/doc commands without prior approval; coordinate before launching full Docker builds or e2e suites that rely on external credentials.
Never commit cached credentials, API keys, or coverage artifacts; CI already handles secrets through GitHub Actions.
Treat prompt and configuration files as single sources of truth—update mirrors (.pr_agent.toml, pr_agent/settings/*.toml) together when behavior changes.

Security and Configuration Tips

Secrets should be supplied through environment variables (see usages in tests/e2e_tests/test_github_app.py and tests/health_test/main.py); do not persist them in code or configuration files.
Adjust runtime behavior by overriding keys in .pr_agent.toml or by supplying repository-specific Dynaconf files; keep overrides minimal and documented inside the PR description.
Review SECURITY.md before disclosing vulnerabilities and follow its contact instructions for responsible reporting.

View Original Source

Related Skills

General

PromptBeginner5 minmarkdown

Untitled Skill

170

Jan 12, 2026

General

PromptBeginner5 minmarkdown

Frontend Typescript Linting.mdc

TypeScript and ESLint rules that MUST be followed when creating, modifying, or reviewing any file under apps/frontend/, including .ts, .tsx, .js, and .jsx files. Also apply when discussing frontend li...

125

Feb 15, 2026

General

PromptBeginner5 minmarkdown

2. Apply Deepthink Protocol (reason about dependencies

risks

116

Jan 15, 2026