Menu
Guide for writing Markdown documentation in this project. Covers GitHub Flavored Markdown pitfalls, especially the critical
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
End-to-end workflow for processing and resolving all Copilot code review suggestions on a pull request in torrust-tracker. Use when asked to handle PR review feedback, process all copilot suggestions, audit and resolve review comments, or manage copilot-generated review threads. Triggers on "process copilot suggestions", "handle all PR feedback", "resolve copilot review", "audit PR suggestions", or "close all copilot comments".
Guide for running a manual Docker security scan for the tracker runtime image and documenting results. Covers build, Trivy scan, CVE triage, per-CVE catalog updates, and scan history updates. Use when asked to run a manual container scan, triage Docker CVEs, or refresh security scan docs.
Use the Torrust Tracker REST API. Covers authentication, all endpoints (stats, metrics, torrents, auth keys, whitelist), and making announce/scrape requests to verify API behaviour. Triggers on "use API", "test API", "call REST API", "query API", "API endpoint", "curl tracker", "tracker client", "announce request", or "verify API".
Run code quality checks and linters for the torrust-tracker project. Includes Rust clippy, rustfmt, markdown, YAML, TOML, spell checking, and shellcheck. Use when asked to lint code, check formatting, fix code quality issues, or prepare for commit. Triggers on "lint", "run linters", "check code quality", "fix formatting", "run clippy", "run rustfmt", or "pre-commit checks".
Guide for fixing Rust Clippy warnings in the torrust-tracker project. Covers proper application of clippy suggestions, when to add allowances, and how to document exceptions. Use when asked to fix clippy warnings, improve code quality, or resolve linter issues. Triggers on "fix clippy", "clippy warnings", "rust code quality", or "linting issues".
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".
| name | write-markdown-docs |
| description | Guide for writing Markdown documentation in this project. Covers GitHub Flavored Markdown pitfalls, especially the critical |
| metadata | {"author":"torrust","version":"1.0"} |
GitHub automatically converts #NUMBER → link to issue/PR/discussion.
❌ Bad: accidentally links to issues
- Task #1: Set up infrastructure ← links to GitHub issue #1
- Task #2: Configure database ← links to GitHub issue #2
Step #1: Install dependencies ← links to GitHub issue #1
The links pollute the referenced issues with unrelated backlinks and confuse readers.
✅ Solution 1: Ordered list (automatic numbering)
1. Set up infrastructure
2. Configure database
3. Deploy application
✅ Solution 2: Plain numbers (no hash)
- Task 1: Set up infrastructure
- Task 2: Configure database
✅ Solution 3: Alternative formats
- Task (1): Set up infrastructure
- Task [1]: Set up infrastructure
Use #NUMBER only when you explicitly want to link to that GitHub issue/PR:
✅ Intentional: referencing issue
This implements the behavior described in #42.
Closes #1697.
@username → links to GitHub user profile (use intentionally for mentions)
abc1234 (SHA) → links to commit (useful for references)
owner/repo#42 → cross-repo issue link
Frontmatter use in docs/ varies by document type: required for issue specs and
EPIC specs, recommended for ADRs and refactor plans, and optional for short
reference pages and README files.
Follow the frontmatter convention defined in
docs/skills/semantic-skill-link-convention.md,
which specifies the required fields for each document type and the shape of
semantic-links entries.
The .markdownlint.json configuration at the repository root applies only to .md files
tracked in the repository. It does not apply to Markdown written on GitHub surfaces such
as issue descriptions, PR descriptions, PR review comments, or discussion posts.
Do not wrap lines when writing GitHub issue or PR body text. Hard-wrapping lines in issue or PR descriptions produces visually broken paragraphs on GitHub's web UI and is harder for human readers to follow. Write each paragraph as a single continuous line and let GitHub's rendering handle the wrapping.
| Surface | Governed by .markdownlint.json | Line wrapping |
|---|---|---|
.md files in repo | Yes | Follow repo config (MD013 disabled, but keep lines readable) |
| GitHub issue / PR body | No | Do not hard-wrap lines |
| GitHub review comments | No | Do not hard-wrap lines |
#NUMBER patterns used for enumeration or step numbering1. 2. 3.)#NUMBER present is an intentional issue/PR referencedocs/skills/semantic-skill-link-convention.mdlinter markdown and linter cspell passApply this checklist to any Markdown body submitted via the GitHub API or CLI (issues, PR descriptions, review comments, discussion posts) before calling the API:
#NUMBER patterns used for enumeration or step numbering#NUMBER present is an intentional issue/PR reference1. 2. 3.)