docs: update style guide rules and add argument hints for skills

Author: marcel-rbro

.claude/README.md

@@ -94,6 +94,7 @@ Before submitting:
 ```bash
 npm run lint:md      # Check markdown
 npm run lint:code    # Check code
+vale "path/to/file.md" --minAlertLevel=error  # Check prose style
 npm start            # Preview changes
 npm test             # Validate API specs
 ```
@@ -103,7 +104,7 @@ npm test             # Validate API specs
 1. **Read `AGENTS.md` first** - Vendor-agnostic documentation standards
 2. **Check `.claude/rules/`** - Auto-loaded standards for writing, formatting, terminology
 3. **Use the appropriate skill** - Designed for specific documentation tasks
-4. **Run linters before committing** - `npm run lint:md` and `npm run lint:code`
+4. **Run linters before committing** - `npm run lint:md`, `npm run lint:code`, and `vale`
 5. **Review before submit** - Use `/review-docs` skill for final checks
 
 ## Need help?

.claude/rules/content-standards.md

@@ -1,9 +1,3 @@
----
-description: Standard formatting rules for all Apify documentation
-globs: ["sources/**/*.md", "sources/**/*.mdx"]
-alwaysApply: true
----
-
 # Content Standards
 
 Canonical formatting standards for all Apify documentation. These rules ensure consistency across platform docs, academy tutorials, and API references.

.claude/rules/file-organization.md

@@ -1,9 +1,3 @@
----
-description: File naming conventions and directory structure standards
-globs: ["sources/**/*"]
-alwaysApply: true
----
-
 # File Organization Rules
 
 ## Naming conventions

.claude/rules/grammar-rules.md

@@ -1,9 +1,3 @@
----
-description: Grammar mechanics and punctuation rules for Apify documentation
-globs: ["sources/**/*.md", "sources/**/*.mdx"]
-alwaysApply: true
----
-
 # Grammar rules
 
 Grammar mechanics and punctuation rules for all Apify documentation. These complement the writing style and terminology guides.
@@ -171,6 +165,5 @@ Use the exact official spelling for tools and brand names:
 | Postgresql, Postgres | PostgreSQL |
 | Jquery | jQuery |
 | Wordpress | WordPress |
-| Elasticsearch | Elasticsearch |
 | VSCode, VS code | VS Code |
 | DockerFile, dockerfile | Dockerfile |

.claude/rules/quality-standards.md

@@ -1,9 +1,3 @@
----
-description: Content quality checklist and review standards
-globs: ["sources/**/*.md", "sources/**/*.mdx"]
-alwaysApply: true
----
-
 # Quality Standards
 
 Comprehensive quality checklist for all Apify documentation. Use this before submitting any content for review.

.claude/rules/terminology.md

@@ -1,9 +1,3 @@
----
-description: Official Apify product and technical terminology
-globs: ["sources/**/*.md", "sources/**/*.mdx", "apify-api/**/*.yaml"]
-alwaysApply: true
----
-
 # Apify Terminology
 
 Official capitalization and usage rules for Apify-specific terms. Use these exact forms throughout all documentation.

.claude/rules/writing-style.md

@@ -1,9 +1,3 @@
----
-description: Comprehensive writing style rules for Apify documentation
-globs: ["sources/**/*.md", "sources/**/*.mdx"]
-alwaysApply: true
----
-
 # Apify Documentation Writing Style
 
 Instructions for AI assistants writing Apify documentation. Based on Apify style guide and technical writer feedback.

.claude/skills/api-doc/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: api-doc
 description: Create or update OpenAPI specifications and API documentation for Apify endpoints. Use when user says "add API endpoint", "create OpenAPI spec", "document this endpoint", "add code samples for API", "update API docs", or "api-doc". Handles OpenAPI YAML, schemas, code samples, and operation IDs.
+argument-hint: endpoint-path
 ---
 
 # API documentation

.claude/skills/doc-write/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: doc-write
 description: Write or edit Apify documentation pages following the style guide. Use when user says "write docs for", "create a new page", "document this feature", "add documentation about", "edit this doc page", or "write a guide for [topic]". Handles platform docs, guides, and reference pages with proper formatting and structure.
+argument-hint: topic
 ---
 
 # Documentation writer

.claude/skills/review-docs/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: review-docs
 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
 ---
 
 # Documentation review
@@ -31,6 +32,7 @@ Review compliance against all standards in `.claude/rules/`:
 ```bash
 npm run lint:md        # Markdownlint - Markdown syntax/formatting
 npm run lint:code      # ESLint - Code linting
+vale "path/to/file.md" --minAlertLevel=error  # Vale - Prose and style
 ```
 
 ## Review checklist
@@ -63,31 +65,6 @@ These aspects require judgment and aren't covered by the rules files:
 - [ ] **Accessibility** - Proper heading hierarchy, descriptive link text, image alt text
 - [ ] **SEO** - Descriptive title, meta description 140-160 chars, internal linking
 
-## How to review
-
-### Step 1: Run automated checks
-
-```bash
-npm run lint:md        # Markdownlint - Markdown syntax/formatting
-npm run lint:code      # ESLint - Code linting
-```
-
-### Step 2: Check style compliance
-
-For each of the rules files listed above, review the content against that file's standards. Use a subagent per file to read the rules and check compliance. Collect all violations.
-
-### Step 3: Content review
-
-Go through the manual content review checklist above. These require human/AI judgment about structure, accuracy, and completeness.
-
-### Step 4: Provide feedback
-
-Format your review using the output template below.
-
-```markdown
-## Documentation review: [File name]
-```
-
 ## Examples
 
 Example 1: Pre-PR review
@@ -97,6 +74,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 `vale "sources/platform/actors/running.md" --minAlertLevel=error`
 1. Check against review checklist
 1. Output structured review with strengths, issues, and priority fixes