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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.