Skip to content

Commit 0900452

Browse files
josecelanojosecelano
committed
docs(agents): add agent skills, pre-commit scripts, git hooks, ADR index, and templates
- Add 19 agent skills under .github/skills/ covering git workflow, maintenance, planning, Rust code quality, and testing - Add scripts/pre-commit.sh: unified pre-commit check runner - Add scripts/install-git-hooks.sh: one-command git hook installer - Add .githooks/pre-commit: checked-in hook delegating to pre-commit.sh - Add docs/adrs/index.md: standalone ADR index table - Update docs/adrs/README.md: replace inline index with link to index.md - Add docs/templates/ADR.md and docs/templates/ISSUE.md - Update project-words.txt: add toplevel, behaviour, autolinks, backlinks, usize - Update docs/issues/1697-ai-agent-configuration.md: mark Task 2 complete
1 parent 9831b24 commit 0900452

29 files changed

Lines changed: 2369 additions & 29 deletions

File tree

‎.githooks/pre-commit‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/usr/bin/env bash
2+
3+
set -euo pipefail
4+
5+
repo_root="$(git rev-parse --show-toplevel)"
6+
7+
"$repo_root/scripts/pre-commit.sh"

‎.github/skills/add-new-skill/SKILL.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
name: add-new-skill
3+
description: Guide for creating effective Agent Skills for the torrust-tracker project. Use when you need to create a new skill (or update an existing skill) that extends AI agent capabilities with specialized knowledge, workflows, or tool integrations. Triggers on "create skill", "add new skill", "how to add skill", or "skill creation".
4+
metadata:
5+
author: torrust
6+
version: "1.0"
7+
---
8+
9+
# Creating New Agent Skills
10+
11+
This skill guides you through creating effective Agent Skills for the Torrust Tracker project.
12+
13+
## About Skills
14+
15+
**What are Agent Skills?**
16+
17+
Agent Skills are specialized instruction sets that extend AI agent capabilities with domain-specific
18+
knowledge, workflows, and tool integrations. They follow the [agentskills.io](https://agentskills.io)
19+
open format and work with multiple AI coding agents (Claude Code, VS Code Copilot, Cursor, Windsurf).
20+
21+
### Progressive Disclosure
22+
23+
Skills use a three-level loading strategy to minimize context window usage:
24+
25+
1. **Metadata** (~100 tokens): `name` and `description` loaded at startup for all skills
26+
2. **SKILL.md Body** (<5000 tokens): Loaded when a task matches the skill's description
27+
3. **Bundled Resources**: Loaded on-demand only when referenced (scripts, references, assets)
28+
29+
### When to Create a Skill vs Updating AGENTS.md
30+
31+
| Use AGENTS.md for... | Use Skills for... |
32+
| ------------------------------- | ------------------------------- |
33+
| Always-on rules and constraints | On-demand workflows |
34+
| "Always do X, never do Y" | Multi-step repeatable processes |
35+
| Baseline conventions | Specialist domain knowledge |
36+
| Rarely changes | Can be added/refined frequently |
37+
38+
**Example**: "Use lowercase for skill filenames" → AGENTS.md rule.
39+
"How to run pre-commit checks" → Skill.
40+
41+
## Core Principles
42+
43+
### 1. Concise is Key
44+
45+
**Context window is shared** between system prompt, conversation history, other skills,
46+
and your actual request. Only add context the agent doesn't already have.
47+
48+
### 2. Set Appropriate Degrees of Freedom
49+
50+
Match specificity to task fragility:
51+
52+
- **High freedom** (text-based instructions): multiple approaches valid, context-dependent
53+
- **Medium freedom** (pseudocode): preferred pattern exists, some variation acceptable
54+
- **Low freedom** (specific scripts): operations are fragile, sequence must be followed
55+
56+
### 3. Anatomy of a Skill
57+
58+
A skill consists of:
59+
60+
- **SKILL.md**: Frontmatter (metadata) + body (instructions)
61+
- **Optional bundled resources**: `scripts/`, `references/`, `assets/`
62+
63+
Keep SKILL.md concise (<500 lines). Move detailed content to reference files.
64+
65+
### 4. Progressive Disclosure
66+
67+
Split detailed content into reference files loaded on-demand:
68+
69+
```markdown
70+
## Advanced Features
71+
72+
See [specification.md](references/specification.md) for Agent Skills spec.
73+
See [patterns.md](references/patterns.md) for workflow patterns.
74+
```
75+
76+
### 5. Content Strategy
77+
78+
- **Include in SKILL.md**: essential commands and step-by-step workflows
79+
- **Put in `references/`**: detailed descriptions, config options, troubleshooting
80+
- **Link to official docs**: architecture docs, ADRs, contributing guides
81+
82+
## Skill Creation Process
83+
84+
### Step 1: Plan the Skill
85+
86+
Answer:
87+
88+
- What specific queries should trigger this skill?
89+
- What tasks does it help accomplish?
90+
- Does a similar skill already exist?
91+
92+
### Step 2: Choose the Location
93+
94+
Follow the directory layout:
95+
96+
```text
97+
.github/skills/
98+
add-new-skill/
99+
dev/
100+
git-workflow/
101+
maintenance/
102+
planning/
103+
rust-code-quality/
104+
testing/
105+
```
106+
107+
### Step 3: Write the SKILL.md
108+
109+
Frontmatter rules:
110+
111+
- `name`: lowercase letters, numbers, hyphens only; max 64 chars; no consecutive hyphens
112+
- `description`: max 1024 chars; include trigger phrases; describe WHAT and WHEN
113+
- `metadata.author`: `torrust`
114+
- `metadata.version`: `"1.0"`
115+
116+
### Step 4: Validate and Commit
117+
118+
```bash
119+
# Check spelling and markdown
120+
linter cspell
121+
linter markdown
122+
123+
# Run all linters
124+
linter all
125+
126+
# Commit
127+
git add .github/skills/
128+
git commit -S -m "docs(skills): add {skill-name} skill"
129+
```
130+
131+
## Directory Layout
132+
133+
```text
134+
.github/skills/
135+
<skill-name>/
136+
SKILL.md ← Required
137+
references/ ← Optional: detailed docs
138+
scripts/ ← Optional: executable scripts
139+
assets/ ← Optional: templates, data
140+
```
141+
142+
## References
143+
144+
- Agent Skills specification: [references/specification.md](references/specification.md)
145+
- Skill patterns: [references/patterns.md](references/patterns.md)
146+
- Real examples: [references/examples.md](references/examples.md)

‎.github/skills/add-new-skill/references/specification.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Agent Skills Specification Reference
2+
3+
This document provides a reference to the Agent Skills specification from [agentskills.io](https://agentskills.io).
4+
5+
## What is Agent Skills?
6+
7+
Agent Skills is an open format for extending AI agent capabilities with specialized knowledge and
8+
workflows. It's vendor-neutral and works with Claude Code, VS Code Copilot, Cursor, and Windsurf.
9+
10+
## Core Concepts
11+
12+
### Progressive Disclosure
13+
14+
```text
15+
Level 1: Metadata (name + description) - ~100 tokens - Loaded at startup for ALL skills
16+
Level 2: SKILL.md body - <5000 tokens - Loaded when skill matches task
17+
Level 3: Bundled resources - On-demand - Loaded only when referenced
18+
```
19+
20+
### Directory Structure
21+
22+
```text
23+
.github/
24+
└── skills/
25+
└── skill-name/
26+
├── SKILL.md # Required: frontmatter + instructions
27+
├── README.md # Optional: human-readable documentation
28+
├── scripts/ # Optional: executable code
29+
├── references/ # Optional: detailed docs loaded on-demand
30+
└── assets/ # Optional: templates, images, data
31+
```
32+
33+
## SKILL.md Format
34+
35+
### Frontmatter (YAML)
36+
37+
```yaml
38+
---
39+
name: skill-name
40+
description: |
41+
What the skill does and when to use it. Include trigger phrases.
42+
metadata:
43+
author: torrust
44+
version: "1.0"
45+
---
46+
```
47+
48+
### Frontmatter Validation Rules
49+
50+
**name**:
51+
52+
- Required; max 64 characters
53+
- Lowercase letters, numbers, hyphens only
54+
- Cannot contain consecutive hyphens or XML tags
55+
56+
**description**:
57+
58+
- Required; max 1024 characters
59+
- Should describe WHAT the skill does AND WHEN to use it
60+
- Include trigger phrases/keywords
61+
62+
## References
63+
64+
- Official spec: <https://agentskills.io/specification>
65+
- GitHub Copilot skills docs: <https://docs.github.com/en/copilot/concepts/agents/about-agent-skills>

‎.github/skills/dev/git-workflow/commit-changes/SKILL.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
name: commit-changes
3+
description: Guide for committing changes in the torrust-tracker project. Covers conventional commit format, pre-commit verification checklist, GPG signing, and commit quality guidelines. Use when committing code, running pre-commit checks, or following project commit standards. Triggers on "commit", "commit changes", "how to commit", "pre-commit", "commit message", "commit format", or "conventional commits".
4+
metadata:
5+
author: torrust
6+
version: "1.0"
7+
---
8+
9+
# Committing Changes
10+
11+
This skill guides you through the complete commit process for the Torrust Tracker project.
12+
13+
## Quick Reference
14+
15+
```bash
16+
# One-time setup: install the pre-commit Git hook
17+
./scripts/install-git-hooks.sh
18+
19+
# Stage changes
20+
git add <files>
21+
22+
# Commit with conventional format and GPG signature (MANDATORY)
23+
# The pre-commit hook runs ./scripts/pre-commit.sh automatically
24+
git commit -S -m "<type>[(<scope>)]: <description>"
25+
```
26+
27+
## Conventional Commit Format
28+
29+
We follow [Conventional Commits](https://www.conventionalcommits.org/) specification.
30+
31+
### Commit Message Structure
32+
33+
```text
34+
<type>[optional scope]: <description>
35+
36+
[optional body]
37+
38+
[optional footer(s)]
39+
```
40+
41+
Scope should reflect the affected package or area (e.g., `tracker-core`, `udp-protocol`, `ci`, `docs`).
42+
43+
### Commit Types
44+
45+
| Type | Description | Example |
46+
| ---------- | ------------------------------------- | ------------------------------------------------------------ |
47+
| `feat` | New feature or enhancement | `feat(tracker-core): add peer expiry grace period` |
48+
| `fix` | Bug fix | `fix(udp-protocol): resolve endianness in announce response` |
49+
| `docs` | Documentation changes | `docs(agents): add root AGENTS.md` |
50+
| `style` | Code style changes (formatting, etc.) | `style: apply rustfmt to all source files` |
51+
| `refactor` | Code refactoring | `refactor(tracker-core): extract peer list to own module` |
52+
| `test` | Adding or updating tests | `test(http-tracker-core): add announce response tests` |
53+
| `chore` | Maintenance tasks | `chore: update dependencies` |
54+
| `ci` | CI/CD related changes | `ci: add workflow for container publishing` |
55+
| `perf` | Performance improvements | `perf(torrent-repository): switch to dashmap` |
56+
57+
## GPG Commit Signing (MANDATORY)
58+
59+
**All commits must be GPG signed.** Use the `-S` flag:
60+
61+
```bash
62+
git commit -S -m "your commit message"
63+
```
64+
65+
## Pre-commit Verification (MANDATORY)
66+
67+
### Git Hook
68+
69+
The repository ships a `pre-commit` Git hook that runs `./scripts/pre-commit.sh`
70+
automatically on every `git commit`. Install it once after cloning:
71+
72+
```bash
73+
./scripts/install-git-hooks.sh
74+
```
75+
76+
Once installed, the hook fires on every commit and you do not need to run the script manually.
77+
78+
### Automated Checks
79+
80+
If the hook is not installed, run the script explicitly before committing.
81+
**It must exit with code `0`.**
82+
83+
> **⏱️ Expected runtime: ~3 minutes** on a modern developer machine. AI agents must set a
84+
> command timeout of **at least 5 minutes** before invoking this script.
85+
86+
```bash
87+
./scripts/pre-commit.sh
88+
```
89+
90+
The script runs:
91+
92+
1. `cargo machete` — unused dependency check
93+
2. `linter all` — all linters (markdown, YAML, TOML, clippy, rustfmt, shellcheck, cspell)
94+
3. `cargo test --doc --workspace` — documentation tests
95+
4. `cargo test --tests --benches --examples --workspace --all-targets --all-features` — all tests
96+
97+
### Manual Checks (Cannot Be Automated)
98+
99+
Verify these by hand before committing:
100+
101+
- **Self-review the diff**: read through `git diff --staged` and check for obvious mistakes,
102+
debug artifacts, or unintended changes
103+
- **Documentation updated**: if public API or behaviour changed, doc comments and any relevant
104+
`docs/` pages reflect the change
105+
- **`AGENTS.md` updated**: if architecture, package structure, or key workflows changed, the
106+
relevant `AGENTS.md` file is updated
107+
- **New technical terms added to `project-words.txt`**: any new jargon or identifiers that
108+
cspell does not know about are added alphabetically
109+
110+
### Debugging a Failing Run
111+
112+
```bash
113+
linter markdown # Markdown
114+
linter yaml # YAML
115+
linter toml # TOML
116+
linter clippy # Rust code analysis
117+
linter rustfmt # Rust formatting
118+
linter shellcheck # Shell scripts
119+
linter cspell # Spell checking
120+
```
121+
122+
Fix Rust formatting automatically:
123+
124+
```bash
125+
cargo fmt
126+
```
127+
128+
## Hashtag Usage Warning
129+
130+
**Only use `#` when intentionally referencing a GitHub issue.**
131+
132+
GitHub auto-links `#NUMBER` to issues. Avoid accidental references:
133+
134+
- ✅ `feat(tracker-core): add feature (see #42)` — intentional reference
135+
- ❌ `fix: make feature #1 priority` — accidentally links to issue #1
136+
137+
Use ordered Markdown lists or plain numbers instead of `#N` step labels.
138+
139+
## Commit Quality Guidelines
140+
141+
### Good Commits (✅)
142+
143+
- **Atomic**: Each commit represents one logical change
144+
- **Descriptive**: Clear, concise description of what changed
145+
- **Tested**: All tests pass
146+
- **Linted**: All linters pass
147+
- **Conventional**: Follows conventional commit format
148+
- **Signed**: GPG signature present
149+
150+
### Commits to Avoid (❌)
151+
152+
- Too large: multiple unrelated changes in one commit
153+
- Vague messages like "fix stuff" or "WIP"
154+
- Missing scope when a package is clearly affected
155+
- Unsigned commits

0 commit comments

Comments
 (0)