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.
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.
Important
Guidelines work like skills, as they are loaded by progressive disclosure.
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 promptsThis 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.
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.
Warning
Using progressive disclosure allows to see when the agent loads a given guideline (or skill), which is harder to detect using instruction files.
This means instructions are only good for encoding some low-level coding preferences, not for moving elaborated preferences.
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.
Tip
In a nutshell, if you declare guidelines in your project, you can just say "do XX respecting project guidelines" and even small models will follow the right ones.
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.
Important
If you use skills to encode your coding standards, use Microsoft APM to do the same than this project does. Actually, this project started because APM does not support guidelines files; see the following Github issue apm#2525.
This tool only installs explicitly selected guidelines:
Put project-owned loading rules in AGENTS.md, CONSTITUTION.md,
or another project convention.
Note
TL;DR: Guidelines are like skills but placed in a different location within the source tree.
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.
uv tool install ai-guidelines
guidelines --versionGit is required for remote sources; local folders need no Git.
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.
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.