chore: agent-agnostic standards, workflows, and skill optimization

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

@@ -0,0 +1,27 @@
+---
+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.
+allowed-tools: Read Write Edit Bash Glob Grep
+argument-hint: endpoint-name
+---
+
+# API documentation
+
+## Process
+
+1. **Identify change type** - new endpoint, update endpoint, add code samples, or new schema
+2. **Follow OpenAPI file structure**:
+   - Paths in `apify-api/openapi/paths/`
+   - Schemas in `apify-api/openapi/components/schemas/`
+   - Code samples in `apify-api/openapi/code_samples/{javascript,curl}/`
+3. **Create or update files** using naming conventions:
+   - Path files: replace `/` with `@` (e.g., `request-queues@{queueId}.yaml`)
+   - Operation IDs: `{objectName}_{httpMethod}` in camelCase
+   - Code sample filenames must match `operationId`
+4. **Register in main spec** - add path `$ref` to `apify-api/openapi/openapi.yaml`
+5. **Validate** - `npm run openapi:lint` then `npm run api:rebuild`
+
+**CRITICAL**: API docs are generated, not hand-written. Never edit files in `apify-api/docs/` directly.
+
+For detailed patterns and examples, see `references/openapi-patterns.md`.
+For edge cases and process notes, see `references/process.md`.

.agents/skills/api-doc/references/process.md

@@ -0,0 +1,70 @@
+# API documentation process
+
+Agent-agnostic workflow for creating or updating OpenAPI specifications and API documentation.
+
+## Step 1: Identify change type
+
+- **New endpoint** - Create path YAML + schema + code samples
+- **Update endpoint** - Edit existing path YAML
+- **Add code samples** - Create files in `code_samples/` directory
+- **New schema** - Create component YAML in `components/schemas/`
+
+## Step 2: Follow OpenAPI file structure
+
+```text
+apify-api/openapi/
+├── openapi.yaml              # Main spec file
+├── components/
+│   └── schemas/              # Data model definitions
+├── paths/                    # API endpoint definitions
+└── code_samples/
+    ├── javascript/           # JS code samples
+    └── curl/                 # cURL code samples
+```
+
+**CRITICAL**: API docs are generated, not hand-written. Never edit files in `apify-api/docs/` directly. Edit the OpenAPI YAML source.
+
+## Step 3: Create or update files
+
+See `references/openapi-patterns.md` for detailed patterns and examples.
+
+Key conventions:
+
+- **Path file naming**: Replace `/` with `@` (e.g., `/request-queues/{queueId}` → `request-queues@{queueId}.yaml`)
+- **Operation IDs**: `{objectName}_{httpMethod}` in camelCase (e.g., `requestQueue_get`)
+- **Code sample filenames**: Must match `operationId` from the spec
+- **Singular vs plural**: Single object for paths with `{id}`, plural otherwise
+
+## Step 4: Register in main spec
+
+Add path references to `apify-api/openapi/openapi.yaml`:
+
+```yaml
+paths:
+  '/request-queues':
+    $ref: './paths/request-queues/request-queues.yaml'
+  '/request-queues/{queueId}':
+    $ref: './paths/request-queues/request-queues@{queueId}.yaml'
+```
+
+## Step 5: Validate and test
+
+```bash
+npm run openapi:lint     # Validate OpenAPI spec (Redocly + Spectral + YAML)
+npm run api:rebuild      # Regenerate API docs
+npm start                # Preview locally
+```
+
+## Edge cases
+
+### OpenAPI validation fails
+
+Run `npm run openapi:lint` for detailed errors. Common issues: unclosed quotes in YAML, missing required fields (`summary`, `operationId`, `responses`), or `$ref` pointing to non-existent files.
+
+### Code samples not appearing in docs
+
+Filename must exactly match the `operationId` from the path YAML. Check build console output - missing samples are logged during `npm run api:rebuild`.
+
+### Generated docs are stale after editing
+
+Run `npm run api:rebuild` to clean and regenerate. The files in `apify-api/docs/` are gitignored and regenerated on every build.

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

@@ -0,0 +1,24 @@
+---
+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.
+allowed-tools: Read Write Edit Bash Glob Grep
+argument-hint: topic
+---
+
+# Documentation writing
+
+## Process
+
+1. **Determine doc type** - platform docs, guide, or reference (tutorials → use `/tutorial`)
+2. **Research** - read related existing pages, check `standards/terminology.md` for product names
+3. **Create front matter** - title (sentence case), description (140-160 chars), sidebar_position, slug
+4. **Write content** following the structure for the doc type:
+   - **Platform docs**: intro → prerequisites → main content → code examples → next steps
+   - **Guides**: intro with goal → step-by-step instructions → verification → troubleshooting
+   - **Reference**: brief description → parameters/options → examples → related pages
+5. **Quality check** - run `npm run lint:md` and `vale` before finishing
+
+Key rules: US English, active voice, imperative tone, sentence case headings, bold for UI elements only, all admonitions need titles, code blocks need language tags.
+
+For detailed structure templates, see `references/doc-structures.md`.
+For edge cases and process notes, see `references/process.md`.

.agents/skills/doc-write/references/process.md

@@ -0,0 +1,59 @@
+# Documentation writing process
+
+Agent-agnostic workflow for writing or editing Apify documentation.
+
+## Step 1: Determine documentation type
+
+| Type | Goal | Location |
+|---|---|---|
+| Platform docs | Practical guidance for features | `sources/platform/` |
+| Guides | Explain how to solve a problem | `sources/platform/` or `sources/academy/` |
+| Reference | Technical specifications | `sources/platform/` |
+| Tutorial | Step-by-step learning | Use the tutorial workflow instead |
+
+## Step 2: Research
+
+- Read 2-3 existing pages in the same directory to match patterns
+- Check `standards/terminology.md` for product name capitalization
+- Identify related pages to link to
+
+## Step 3: Create front matter
+
+```yaml
+---
+title: Sentence case title
+description: 140-160 character value-focused description
+sidebar_position: 1.0
+slug: /path/to/page
+---
+```
+
+## Step 4: Write content
+
+Follow the structure template for the doc type in `references/doc-structures.md`:
+
+- **Platform docs**: introduction → when to use → configure/use → best practices → related features
+- **Guides**: introduction → prerequisites → step-by-step → code examples → testing → summary
+- **Reference**: overview → parameters/options → examples → related information
+
+## Step 5: Quality check
+
+- Run `npm run lint:md` on the new or edited file
+- Run `vale "<file>" --minAlertLevel=error`
+- Run `npm start` (or `npm run build`) to verify no broken links or slug conflicts
+
+Key rules: US English, active voice, imperative tone, sentence case headings, bold for UI elements only, all admonitions need titles, code blocks need language tags.
+
+## Edge cases
+
+### Editing existing pages
+
+Read the full existing page before making changes. Preserve the existing structure and voice. Only modify what's needed.
+
+### Description length
+
+Front matter `description` must be 140-160 characters for SEO. Focus on user value, not feature lists.
+
+### Page doesn't match sibling pages
+
+Before writing, read sibling pages in the same directory. Match heading structure, code example style, and admonition usage.

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

@@ -0,0 +1,33 @@
+---
+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.
+allowed-tools: Read Bash Glob Grep Agent
+model: sonnet
+argument-hint: file-path
+---
+
+# Documentation review
+
+## Process
+
+1. **Verify file version** - `git status` to confirm you have the latest
+2. **Run deterministic checks** (main process) - these are objective, no judgment needed:
+   - `npm run lint:md` (heading hierarchy, list numbering, spacing)
+   - `vale "<file>" --minAlertLevel=error` (prose style, pronouns, dashes, code fences, admonitions)
+   - `scripts/check-frontmatter.sh "<file>"` (description char count)
+3. **Delegated standards review** - spawn one subagent per standards file to check compliance. Each subagent reads the file being reviewed plus one standards file, and returns violations with line numbers and suggested fixes:
+   - Subagent 1: check against `standards/writing-style.md` (voice, tone, headings, links)
+   - Subagent 2: check against `standards/content-standards.md` (front matter, admonitions, code blocks)
+   - Subagent 3: check against `standards/terminology.md` (product names, article usage)
+   - Subagent 4: check against `standards/grammar-rules.md` (hyphenation, punctuation, brand spelling)
+   Launch all 4 in parallel.
+4. **Content review** (main process) - focus on what standards files don't cover:
+   - Content structure (clear intro, logical flow, next steps)
+   - Technical accuracy (code examples correct, API endpoints current)
+   - Completeness (prerequisites listed, edge cases covered)
+   - Code example quality (complete, runnable, commented where needed)
+5. **Format output** - merge subagent findings + deterministic results + content review per `references/review-format.md`
+
+Deterministic tools first, then delegated standards checks, then content review. Report tool failures as objective facts. Report standards and content findings as judgment calls.
+
+For detailed process notes and edge cases, see `references/process.md`.

.agents/skills/review-docs/references/process.md

@@ -0,0 +1,63 @@
+# Documentation review process
+
+Agent-agnostic workflow for reviewing Apify documentation.
+
+## Step 1: Verify latest file version
+
+- Run `git status` to check for unsaved changes
+- If reviewing a PR: `git fetch && git checkout <branch>` to ensure the branch is current
+
+## Step 2: Run deterministic checks
+
+These are objective - no judgment needed. Report all failures. Run in the main process (not in subagents).
+
+- `npm run lint:md` (markdownlint: heading hierarchy, double spaces, list numbering)
+- `vale "<file>" --minAlertLevel=error` (prose style, dashes, code fences, admonitions)
+- `scripts/check-frontmatter.sh "<file>"` (description char count)
+
+## Step 3: Delegated standards review
+
+Spawn one subagent per standards file to check compliance in parallel. Each subagent reads the file being reviewed plus one standards file, and returns violations with line numbers and suggested fixes.
+
+- Subagent 1: check against `standards/writing-style.md` (voice, tone, headings, links)
+- Subagent 2: check against `standards/content-standards.md` (front matter, admonitions, code blocks)
+- Subagent 3: check against `standards/terminology.md` (product names, article usage)
+- Subagent 4: check against `standards/grammar-rules.md` (hyphenation, punctuation, brand spelling)
+
+Why subagents: each standards file gets dedicated attention. A single-pass review with a summary tends to miss edge cases (comma rules, article usage, brand spelling) that a focused read catches.
+
+Why not deterministic tools in subagents: subagents may have sandbox restrictions that prevent running Bash commands. Keep all tool execution in the main process.
+
+## Step 4: Content review
+
+Run in the main process. Focus on what neither deterministic tools nor standards files cover:
+
+- [ ] Content structure (clear intro, logical progression, next steps)
+- [ ] Technical accuracy (code examples correct, API endpoints current)
+- [ ] Completeness (prerequisites listed, edge cases addressed)
+- [ ] Text formatting judgment (is bold usage for a UI element or misuse?)
+- [ ] Link quality beyond "click here" (is the text genuinely descriptive?)
+- [ ] Code example quality (complete, runnable, commented where needed)
+
+## Step 5: Format output
+
+Merge deterministic results + subagent findings + content review into structured output per `references/review-format.md`.
+
+- Tool findings are objective facts
+- Standards findings are rule-based judgment calls
+- Content findings are subjective judgment calls
+- Prioritize by impact: critical → important → minor
+
+## Edge cases
+
+### Reviewing generated API docs
+
+Never review files in `apify-api/docs/` - they're generated. Review the OpenAPI YAML source in `apify-api/openapi/` instead.
+
+### Reviewing pages with code tabs
+
+Check that both JavaScript and Python examples are present and functionally equivalent. Verify code tab syntax matches the Docusaurus `Tabs`/`TabItem` pattern.
+
+### Markdownlint false positives on admonitions
+
+Markdownlint doesn't understand Docusaurus `:::` syntax natively. Check `.markdownlint.json` for configured exceptions. Focus on Vale for prose quality.

.agents/skills/review-docs/scripts/check-frontmatter.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Validates front matter description is 140-160 characters.
+# Usage: check-frontmatter.sh <file-path>
+
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+    echo "Usage: $0 <file-path>"
+    exit 1
+fi
+
+FILE="$1"
+
+if [ ! -f "$FILE" ]; then
+    echo "FAIL: File not found: $FILE"
+    exit 1
+fi
+
+# Extract description from YAML front matter
+DESCRIPTION=$(awk '/^---$/{if(++c==2)exit}c==1&&/^description:/{sub(/^description:\s*/, ""); gsub(/^["'\''"]|["'\''"]$/, ""); print}' "$FILE")
+
+if [ -z "$DESCRIPTION" ]; then
+    echo "FAIL: No description found in front matter"
+    exit 1
+fi
+
+LENGTH=${#DESCRIPTION}
+
+if [ "$LENGTH" -ge 140 ] && [ "$LENGTH" -le 160 ]; then
+    echo "PASS: Description is $LENGTH characters (140-160 range)"
+    exit 0
+else
+    echo "FAIL: Description is $LENGTH characters (expected 140-160)"
+    echo "  Description: $DESCRIPTION"
+    exit 1
+fi

.agents/skills/tutorial/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: tutorial
+description: Create structured tutorials for Apify Academy or Platform documentation. Use when user says "create a tutorial", "write a tutorial", "build a step-by-step guide", "convert this guide into a tutorial", or "tutorial for [topic]". Handles tutorial structure, learning objectives, prerequisites, step-by-step instructions, code examples, and troubleshooting sections.
+allowed-tools: Read Write Edit Bash Glob Grep
+argument-hint: topic
+---
+
+# Tutorial creation
+
+## Process
+
+1. **Identify tutorial type** - platform tutorial, academy tutorial, or integration tutorial
+2. **Research** - read related docs, check existing tutorials for style reference
+3. **Create front matter** - title (sentence case), description (140-160 chars), sidebar_position, slug
+4. **Write 8-section structure**:
+   1. Introduction with learning objectives
+   2. Prerequisites (tools, accounts, knowledge)
+   3. Step-by-step instructions (numbered, action verbs)
+   4. Code examples (complete, runnable, tested)
+   5. Testing and verification (expected results)
+   6. Troubleshooting (common issues + fixes)
+   7. Summary (what was learned)
+   8. Next steps (links to related content)
+5. **Quality check** - run `npm run lint:md` and `vale` before finishing
+
+Each step should have a clear action verb, expected result, and verification. Code examples must be complete - no pseudocode.
+
+For the detailed 8-section template, see `references/tutorial-template.md`.
+For edge cases and process notes, see `references/process.md`.