Skip to main content

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. Add -v (steps) or -vv (Git commands and their output) before any command to diagnose a failure, for example guidelines -vv add ....

Adding a file or a folder

guidelines add takes a source and an optional repository-relative selector. The selector is installed immediately and recorded in guidelines.yml.

Select one file (the suffix is optional):

$ guidelines add gsemet/ai-guidelines-registry SWE/Git/Git_Commit_Message/git-commit-message.guidelines.md
$ guidelines add gsemet/ai-guidelines-registry SWE/Git/Git_Commit_Message/git-commit-message

Select a folder: every *.guideline.md and *.guidelines.md file below it is captured, recursively, and flattened into the target folder. Other files, such as a leaf README.md, are skipped.

$ guidelines add gsemet/ai-guidelines-registry SWE/Git/Git_Commit_Message
$ guidelines add gsemet/ai-guidelines-registry SWE/Python

The second command installs both python-module-documentation.guidelines.md and python-unittest.guidelines.md, found in two different subfolders of SWE/Python.

A selector without a / is a filename pattern matched anywhere in the source:

$ guidelines add gsemet/ai-guidelines-registry "python-*"

Searching a source

guidelines search is recursive by default: it lists every guideline file anywhere below the source location, whatever its folder depth. The optional query is a glob matched against the filename, with or without its suffix.

$ guidelines search gsemet/ai-guidelines-registry
$ guidelines search gsemet/ai-guidelines-registry "*commit*"
$ guidelines search gsemet/ai-guidelines-registry/SWE/Python

Each result shows the filename, the source, the source-relative path to pass to guidelines add, and whether it is already installed. Without a location, guidelines search --query GLOB searches the sources declared in guidelines.yml.

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.3.0

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

Source distribution (sdist)

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

Built distribution (wheel)

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

Total release size: 416.0 kB

Release files / ai_guidelines-1.3.0.tar.gz

Download URL ai_guidelines-1.3.0.tar.gz
Size 324.3 kB
Tags Source
SHA-256 checksum
How to use checksums
b33d39d2fdb933a330d318124b74841081f3b432da321fa305470b921cab9f1f
BLAKE2b-256 checksum
How to use checksums
cb2176c31522d3816f7c5cee7242e6731c9d30c68558321997b8134a0c303b53
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 Oct 15, 2026.

Transparency log

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

Download URL ai_guidelines-1.3.0-py3-none-any.whl
Size 91.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8f68a0f6506702a4700f71528855ff12cf573e0c13e7645495bd5ffba6a24e39
BLAKE2b-256 checksum
How to use checksums
aff609e95308d5df98c3c35afedd13ad3852de3f11b5efdbf92d0ac018fbb0e9
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 Oct 15, 2026.

Transparency log

Security for ai-guidelines 1.3.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ai_guidelines-1.3.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 Oct 15, 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