From 1a829c0bbb278465c7d123313a1c772a32af8f2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Thu, 12 Mar 2026 12:16:33 +0100
Subject: [PATCH] chore(skills): improve review-docs, doc-write, and tutorial
 skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add Agent to review-docs allowed-tools so subagent delegation works
without prompting
  - Expand review-docs Step 1 with actionable git commands for verifying
file state
  - Standardize lint command in review-docs example (npx markdownlint →
npm run lint:md)
  - Add lint and build verification steps to doc-write and tutorial
quality checklists
---
 .claude/skills/doc-write/SKILL.md   | 2 ++
 .claude/skills/review-docs/SKILL.md | 9 ++++++---
 .claude/skills/tutorial/SKILL.md    | 2 ++
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/.claude/skills/doc-write/SKILL.md b/.claude/skills/doc-write/SKILL.md
index a44d71623b..ffbb265313 100644
--- a/.claude/skills/doc-write/SKILL.md
+++ b/.claude/skills/doc-write/SKILL.md
@@ -53,6 +53,8 @@ All standards from `.claude/rules/` apply. Key doc-write checks:
 - [ ] Each step has clear instructions
 - [ ] Related documentation is linked
 - [ ] No assumptions about product features (ask if unsure)
+- [ ] Run `npm run lint:md` on the new or edited file
+- [ ] Run `npm start` (or `npm run build`) to verify no broken links or slug conflicts
 
 For the complete quality checklist, see `quality-standards.md`.
 
diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md
index 0d0a37613b..ff4b114198 100644
--- a/.claude/skills/review-docs/SKILL.md
+++ b/.claude/skills/review-docs/SKILL.md
@@ -1,7 +1,7 @@
 ---
 description: Review Apify documentation for style guide compliance, quality standards, and best practices. Use when user says "review this doc", "check this page", "audit documentation", "review before PR", "is this ready to publish", or "review-docs". Runs automated checks and manual review against Apify style guide.
 argument-hint: file-path
-allowed-tools: Read, Bash, Glob, Grep
+allowed-tools: Read, Bash, Glob, Grep, Agent
 ---
 
 # Documentation review
@@ -12,7 +12,10 @@ Review documentation for compliance with Apify style guide, quality standards, a
 
 ### Step 1: Check latest changes
 
-**CRITICAL**: Verify you're reviewing the latest version of the file. If reviewing a PR, confirm the branch is up to date.
+**CRITICAL**: Verify you're reviewing the latest version of the file before starting.
+
+- If reviewing a local file: confirm no unsaved changes with `git status`
+- If reviewing a PR: run `git fetch && git checkout <branch>` to ensure the branch is current
 
 ## Standards reference
 
@@ -73,7 +76,7 @@ User says: "Review sources/platform/actors/running.md before I submit"
 
 Actions:
 1. Read the file
-1. Run `npx markdownlint "sources/platform/actors/running.md"`
+1. Run `npm run lint:md` (or `npx markdownlint "sources/platform/actors/running.md"` for a single file)
 1. Run `vale "sources/platform/actors/running.md" --minAlertLevel=error`
 1. Check against review checklist
 1. Output structured review with strengths, issues, and priority fixes
diff --git a/.claude/skills/tutorial/SKILL.md b/.claude/skills/tutorial/SKILL.md
index 81f3d24cbe..8c86b6124b 100644
--- a/.claude/skills/tutorial/SKILL.md
+++ b/.claude/skills/tutorial/SKILL.md
@@ -56,6 +56,8 @@ All standards from `.claude/rules/` apply. Key tutorial-specific checks:
 - [ ] Common issues addressed in troubleshooting
 - [ ] Summary lists what user accomplished
 - [ ] Next steps and related content linked
+- [ ] Run `npm run lint:md` on the new file
+- [ ] Run `npm start` (or `npm run build`) to verify no broken links or slug conflicts
 
 For general quality standards (front matter, formatting, terminology), see `quality-standards.md`.