Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,10 @@
*.pptx filter=lfs diff=lfs merge=lfs -text
*.pdf filter=lfs diff=lfs merge=lfs -text

# Temporary while checked in, will be auto-generated later on CI.
src/agents/all* filter=lfs diff=lfs merge=lfs -text


# Make it look like a Rust project to GitHub's linguist.
*.scss linguist-detectable=false
*.html linguist-detectable=false
*.md linguist-detectable=false
*.css linguist-detectable=false
*.js linguist-detectable=false
*.sh linguist-detectable=false

4 changes: 2 additions & 2 deletions .github/workflows/common.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ jobs:
- name: Preprocess
run: |
chmod +x ./scripts/*.sh
bash ./scripts/agents_summary.sh
bash ./scripts/agents_meta.sh
python3 scripts/test_build_skill.py
python3 scripts/build_skill.py
bash ./scripts/build_date.sh

- name: MdBook Test
Expand Down
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,5 @@ output
.idea
*.local.json
.*/**/*.md

/src/agents/pragmatic-rust-guidelines.zip
__pycache__/
10 changes: 9 additions & 1 deletion CLAUDE.md → AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!-- markdownlint-disable no-bare-urls -->

# CLAUDE.md
# AGENTS.md

## Repository Overview

Expand All @@ -11,6 +11,8 @@ This repository contains the **Pragmatic Rust Guidelines** - a collection of des
```bash
mdbook serve --open # Previews page
mdbook build # Builds page
python3 scripts/build_skill.py # Generates the distributable agent skill
python3 scripts/test_build_skill.py # Tests skill packaging
```

Requires [mdbook](https://github.com/rust-lang/mdBook) to be installed.
Expand All @@ -35,13 +37,19 @@ Content with code examples...
- `src/SUMMARY.md` - mdBook table of contents
- `src/guidelines/checklist/README.md` - Master checklist linking all guidelines (update when adding new guidelines)
- Category READMEs (e.g., `src/guidelines/universal/README.md`) - Include guidelines via mdBook's `{{#include}}` directive
- `skill/SKILL.md` - Template for the skill distributed to other Rust repositories, not installed for this repository
- `scripts/build_skill.py` - Bundles canonical guidelines, category catalogs, and images into the downloadable skill

## Adding New Guidelines

1. Create `M-YOUR-GUIDELINE.md` in the appropriate category folder
2. Add the guideline to the category's `README.md` using `{{#include M-YOUR-GUIDELINE.md}}`
3. Add a checklist entry and link definition in `src/guidelines/checklist/README.md`

After changing guidelines or the skill template, regenerate the archive with `python3 scripts/build_skill.py`.
Do not maintain separate authored copies of the reference Markdown.
The build requires the guideline images to be downloaded through Git LFS.

Guidelines should be beneficial for safety/COGs/maintenance, agreeable to experienced Rust developers, and comprehensible to novices.

## Editing Guidelines
Expand Down
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ A collection of pragmatic design guidelines helping developers to produce idioma

👉 [**Pragmatic Rust Guidelines**](https://microsoft.github.io/rust-guidelines)

## Agent Skill

Use the [Pragmatic Rust Guidelines agent skill](src/agents/README.md) in your own Rust repository.
The downloadable package contains instructions, category catalogs, the guideline Markdown, and its supporting images.
Agents can read relevant guidelines without loading the entire book or checking out this repository.

## Development

The guidelines use [mdbook](https://github.com/rust-lang/mdBook). Once installed you can view them locally via
Expand All @@ -12,6 +18,16 @@ The guidelines use [mdbook](https://github.com/rust-lang/mdBook). Once installed
mdbook serve --open
```

To build the distributable skill download, run:

```bash
python3 scripts/build_skill.py
```

The archive is generated at `src/agents/pragmatic-rust-guidelines.zip` and included in the published book.
The `skill/` directory contains the packaging template, not a skill installed for this repository.
The build requires the guideline images to be downloaded through Git LFS.

To submit new guidelines, file a PR. They should be

- beneficial for { safety, COGs, maintenance },
Expand Down
78 changes: 0 additions & 78 deletions scripts/agents_meta.sh

This file was deleted.

147 changes: 0 additions & 147 deletions scripts/agents_summary.sh

This file was deleted.

Loading
Loading