Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

ai-guidelines

ai-guidelines manages reusable Markdown guidelines for a project.

It allows users to declare dependencies on reference guidelines (on a reference git project) and copy/update them.

What are guidelines?

A guideline is reusable Markdown context containing rules or practices. It is declared in the project context (usually in AGENTS.md), and the agent identifies when it has to use it, especially during planning.

Any example?

Sure, look at this very project! For instance, look at how .github/guidelines/git-commit-message.guidelines.md declares the rules for writing conventional Git commit messages in this project, and how it is referenced in AGENTS.md.

This means the pointer to the rules for writing Git commit messages is always in the start of the Context Windows, so it is in the zone of attention of the LLM. Any agent working in this project will naturally follow this convention, even if it does not have the same set of skills or plugins installed as the original author.

Also note the clear precedence rules in AGENTS.md:

Precedence rule:

- CONSTITUTION > AGENTS.md > Guidelines > skills > other prompts

This means that a guideline that is meant to be reusable across several projects can conflict with another rule. The CONSTITUTION.md and AGENTS.md take precedence, giving the agent the correct guidance on which rules to follow.

Note that for small projects, CONSTITUTION.md or equivalent is not really needed. But since AGENTS.md is always in context it should not grow too much. When it becomes too large, move the rules to modify your project to a dedicated CONSTITUTION.md file.

They are written in this project. They are actually declared in guidelines.yml and are recopied into the project's guidelines folder when guidelines update is run (see the justfile).

They are maintained in the sister-project Guidelines Registry.

Why not instructions or rules?

An instruction file is a GitHub Copilot specific file that is loaded or injected by the Coding Agent according to its file-pattern rules. During planning, when the agent is thinking about the files to edit, for instance, the coding agent does not see any file of this type opened, and so may not have loaded the relevant instruction files at this point.

This means instructions are only good for encoding some low-level coding preferences, not for moving elaborated preferences.

Why not use skills?

You can definitely use skills to encode your coding standard preferences. But they will all be placed in a single location in your project (for example, .github/skills/), making them hard to distinguish from other skills for you and your agent.

A skill is a self-describing knowledge package that declares activation or loading behavior. A Skill can contain coding standards and act exactly like guidelines, but it is good to place it in a separate location with a clear name.

This tool only installs explicitly selected guidelines: Put project-owned loading rules in AGENTS.md, CONSTITUTION.md, or another project convention.

Guideline, instruction, and skill

A guideline is reusable Markdown context containing rules or practices. It is declared in the project context (usually in AGENTS.md) and the agent idenfies when it will have to use it, especially during planning.

An instruction file is a GitHub Copilot specific file that is loaded or injected by the Coding Agent according to its file-pattern rules. During planning, when the agent is thinking about the files to edit for instance, the coding agent does not see any file of this type opened, and so MAY not have loaded the relevant instruction files at this point. This means instructions are only good to encode some low level coding preference, not move elaborated preferences.

A skill is a self-describing knowledge package that declares activation or loading behavior. A Skill can contain coding standards, and act exactely like guidelines, but it is good to place them in a separate location with a clear name.

This tool only installs explicitly selected guidelines: Put project-owned loading rules in AGENTS.md, CONSTITUTION.md, or another project convention.

Install

uv tool install ai-guidelines

guidelines --version

Git is required for remote sources; local folders need no Git.

Quick start

Create guidelines.yml:

version: 1
default_guidelines_path: .github/guidelines
guidelines:
  - source: https://github.com/example/team-guidelines.git
    ref: main
    pattern: "*.guideline.md"

Run guidelines sync, then guidelines list, guidelines search LOCATION QUERY, guidelines outdated, or guidelines update --dry-run. Add sources with guidelines add LOCATION [PATTERN] --ref REF --target-path PATH --alias NAME and remove declarations with guidelines remove IDENTIFIER; installed files are preserved. sync --dry-run previews changes, while sync --frozen replays complete locked state without resolution or writes. Use --refresh and --no-cache with search, and guidelines cache size to inspect the cache. Selectors match both .guideline.md and .guidelines.md source files, including when the suffix is omitted. Missing source paths are reported as concise CLI errors rather than Python tracebacks. Installed files always use the canonical .guidelines.md suffix.

Documentation

Full documentation (tutorials, how-to guides, CLI and format reference, and design rationale) is at https://ai-guidelines.readthedocs.io/.

Start with the getting-started tutorial. To publish guidelines for your own team, commit them to a Git repository and declare it as a source: see source grammar. For how acquired sources are cached, see how caching works.

See also SECURITY.md and the examples/ directory.

Metadata

Release files for ai-guidelines 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for ai-guidelines 1.2.0
File Size Uploaded Provenance Actions
ai_guidelines-1.2.0.tar.gz 317.4 kB With provenance Details for ai_guidelines-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-guidelines 1.2.0
File Interpreter ABI Platform Actions
ai_guidelines-1.2.0-py3-none-any.whl Python 3 none any Details for ai_guidelines-1.2.0-py3-none-any.whl

Total release size: 407.3 kB

Release files / ai_guidelines-1.2.0.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL ai_guidelines-1.2.0.tar.gz
Size 317.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5bf1309faa732bbebdd78021a35cab4ab1a552b83802f22664059b333f77f25a
BLAKE2b-256 checksum
How to use checksums
11966e8d2cf7796f5c5b5d9758679e1f7a472688b8a8b8ae1c889be6c71777f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.

Transparency log

Release files / ai_guidelines-1.2.0-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL ai_guidelines-1.2.0-py3-none-any.whl
Size 90.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c8e8f8b3cbaaf13be104cf74b2b831a966f5c7d93b898dd559cef74277dfdffd
BLAKE2b-256 checksum
How to use checksums
d5ddd929e65b5fc71299c96c7b527abe62465fa584863f65de22613586314921
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.

Transparency log

Security for ai-guidelines 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Change of provenance

The configuration that created this release differs from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for ai_guidelines-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page