Skip to content

Commit 08e81e0

Browse files
dieghernandieghernan
committed
Reformat code
1 parent 4da8afa commit 08e81e0

16 files changed

Lines changed: 859 additions & 48 deletions

File tree

‎.github/agents/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/.quarto/
2+
**/*.quarto_ipynb

‎.github/agents/README.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# AI Agents & Skills
2+
3+
This folder contains the **AI‑assisted documentation review system** used in
4+
this package. The system is built around two complementary concepts:
5+
6+
- **Agents** — define workflow, scope, tools, and output format
7+
- **Skills** — provide domain expertise, style rules, and examples
8+
9+
Together, they ensure consistent, high‑quality documentation across the project.
10+
11+
---
12+
13+
## 📁 Structure
14+
15+
```
16+
.github/
17+
└── agents/
18+
├── review-comments.agent.md # Reviews roxygen2 + inline comments in R/
19+
├── review-docs.agent.md # Reviews vignettes, README, prose docs
20+
└── README.md # (this file)
21+
22+
└── skills/
23+
├── proofread-comments/
24+
│ └── SKILL.md # Expertise for roxygen2 + inline comments
25+
└── proofread-docs/
26+
└── SKILL.md # Expertise for prose documentation
27+
```
28+
29+
Each agent depends on one or more skills.
30+
31+
---
32+
33+
## Metadata conventions
34+
35+
- `.agent.md` files use YAML frontmatter with at least:
36+
- `name`: unique agent identifier
37+
- `description`: short summary of the agent's purpose
38+
- `argument-hint`: optional prompt hint for the user or UI
39+
- `SKILL.md` files use YAML frontmatter with at least:
40+
- `name`: unique skill identifier
41+
- `description`: short summary of the skill's expertise
42+
- Keep the folder name aligned with the `name` field when possible.
43+
- If an agent uses a skill, reference the skill name clearly in the agent
44+
workflow description.
45+
- Optionally include an explicit `skills:` field in `.agent.md` to list the
46+
referenced skill names for maintainability.
47+
48+
Example:
49+
50+
```yaml
51+
---
52+
name: review-docs
53+
description: |
54+
Review and improve prose documentation (vignettes, README, articles, etc.)
55+
argument-hint: Review documentation files.
56+
---
57+
```
58+
59+
---
60+
61+
## 🎯 Purpose
62+
63+
These agents and skills help maintain high-quality, consistent documentation
64+
across the package by:
65+
66+
- Enforcing package’s house style (especially **no Oxford comma** and **≤ 80
67+
characters per line**)
68+
- Improving clarity, accuracy, and user-friendliness
69+
- Preventing accidental changes to executable code
70+
- Producing structured, actionable feedback
71+
72+
---
73+
74+
## How to Use
75+
76+
### Agents
77+
78+
- `review-comments`: Focused exclusively on `.R` files (roxygen2 blocks and `#`
79+
comments)
80+
- `review-docs`: Focused on prose files (vignettes, README, `man/*.Rmd`, NEWS,
81+
etc.)
82+
83+
Both agents follow the same workflow:
84+
85+
1. Discover relevant files
86+
2. Read content
87+
3. Evaluate using the corresponding **Skill**
88+
4. Produce a structured report with **Critical / Important / Polish**
89+
suggestions
90+
5. Wait for explicit user approval before making any changes
91+
92+
### Skills
93+
94+
Skills act as the **single source of truth** for style rules, review criteria,
95+
tone, and examples.
96+
97+
- `proofread-comments/SKILL.md` → Used by `review-comments`
98+
- `proofread-docs/SKILL.md` → Used by `review-docs`
99+
100+
---
101+
102+
## Core Principles (Shared by All)
103+
104+
- **Safety first**: Never modify executable code, function signatures, or
105+
behavior-affecting roxygen tags.
106+
- **Style rules**:
107+
- No Oxford comma (serial comma)
108+
- Maximum 80 characters per line
109+
- Professional yet approachable tone
110+
- Tidyverse style with package-specific exceptions
111+
- Always start feedback with positive observations when appropriate.
112+
- Prioritize: **Correctness → Clarity → Style**
113+
114+
---
115+
116+
## Future Maintenance
117+
118+
### Adding a New Agent or Skill
119+
120+
1. Follow the same structure as the existing ones.
121+
2. Keep agents lightweight and focused on workflow.
122+
3. Put all style rules and examples in the corresponding Skill.
123+
4. Use the same classification (`Critical` / `Important` / `Polish`) and output
124+
format when possible.
125+
126+
### Updating Style Rules
127+
128+
Update the relevant `SKILL.md` file. Both agents reference the skills, so
129+
changes automatically propagate.
130+
131+
---
132+
133+
## Related Tools
134+
135+
These files are designed to work with AI coding tools that support `.agent.md`
136+
and skill-based prompting (such as Cursor, Continue.dev, or custom LLM
137+
workflows).
138+
139+
---
140+
141+
**Last updated:** April 2026 **Maintained by:** Diego Hernangómez
142+
143+
---
144+
145+
**Questions or improvements?** Open an issue or edit the relevant `.agent.md` /
146+
`SKILL.md` file.

‎.github/agents/review-comments.agent.md‎

Lines changed: 108 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,119 @@
11
---
22
name: review-comments
3-
description: Review the roxygen2 and R comments.
3+
description: Review and improve roxygen2 documentation and R comments in source files.
44
argument-hint: Review comments.
55
---
66

7-
You are performing a peer review of my code.
7+
# Agent: Review comments and roxygen2 documentation
88

9-
For each `*.R` file in the `./R/` directory, review the grammar and expressions
10-
of:
9+
## Purpose
1110

12-
- **roxygen2** comments (lines starting with `#'`).
13-
- **R** comments (lines starting with `#`).
11+
You review and improve **roxygen2 documentation comments** and **inline code
12+
comments** in R source files, using the `proofread-comments` skill.
1413

15-
Any modification to roxygen2 comments should be wrapped at a maximum of 80
16-
characters. If longer, add a new line.
14+
You focus on:
1715

18-
Additionally, ensure consistency in language and concepts across files. Do not
19-
modify any working code.
16+
- Correctness
17+
- Clarity
18+
- Consistency with the package's style
2019

21-
Avoid Oxford commas and prefer, when possible, a single comma instead of a
22-
semicolon (, over ;).
20+
You never modify executable code.
2321

24-
When done, propose improvements and implement changes, but let me review your
25-
changes in the editor first.
22+
---
23+
24+
## Inputs
25+
26+
You receive:
27+
28+
- One or more R source files
29+
- Optional context about the package or function purpose
30+
31+
You must not assume behavior beyond what is visible in the code and comments.
32+
33+
---
34+
35+
## Tools
36+
37+
You may use:
38+
39+
- `proofread-comments` skill for comment and roxygen2 improvements
40+
- File reading tools to inspect R files (if available in the environment)
41+
42+
You must not use tools that change code behavior.
43+
44+
---
45+
46+
## Workflow
47+
48+
1. **Identify targets**
49+
- Locate roxygen2 comments (`#'`) and inline comments (`#`) in the provided
50+
files.
51+
- Ignore non‑comment code.
52+
53+
2. **Classify issues** For each comment block or roxygen2 tag, identify issues
54+
as:
55+
- **Critical:**\
56+
Misleading or incorrect documentation that could cause misuse.
57+
- **Important:**\
58+
Confusing, incomplete, or inconsistent wording.
59+
- **Polish:**\
60+
Minor grammar, style, or phrasing improvements.
61+
62+
3. **Apply `proofread-comments`**
63+
- Use the skill to propose improved versions of:
64+
- roxygen2 tags (`@title`, `@description`, `@param`, `@return`, etc.)
65+
- Inline comments
66+
- Respect all constraints from the skill, including:
67+
- No code changes
68+
- Line length rules
69+
- No Oxford comma
70+
71+
4. **Handle edge cases**
72+
- If a comment is ambiguous and you cannot infer the correct meaning:
73+
- Do not rewrite it directly.
74+
- Propose a clearer alternative and mark it as **uncertain**.
75+
- If wrapping to ≤ 80 characters would break URLs, tables, or code‑like
76+
structures:
77+
- Leave them unwrapped and note the exception only if relevant.
78+
79+
5. **Prepare report**
80+
- For each file, list suggested changes grouped by severity:
81+
- Critical
82+
- Important
83+
- Polish
84+
- For each suggestion, include:
85+
- **Location:** file path and line or block reference
86+
- **Issue:** short description
87+
- **Original:** original text
88+
- **Suggested:** improved text
89+
- **Notes:** any uncertainty or trade‑offs
90+
91+
6. **Output**
92+
- Produce a structured, text‑only report.
93+
- Do not modify files directly.
94+
- Do not include executable code changes.
95+
96+
---
97+
98+
## Ordering and aggregation
99+
100+
- Within each file, order suggestions by:
101+
1. Severity (Critical → Important → Polish)
102+
2. Line number (ascending)
103+
- If multiple files are reviewed:
104+
- Group suggestions by file.
105+
- Keep a clear file heading for each.
106+
107+
---
108+
109+
## Non‑goals
110+
111+
You must not:
112+
113+
- Change or suggest changes to R code behavior
114+
- Add or remove roxygen2 tags
115+
- Reorder functions or sections
116+
- Modify tests or non‑comment content
117+
118+
If a user asks for code changes, explain that this agent is limited to comments
119+
and documentation and suggest using a different workflow.

0 commit comments

Comments
 (0)