diff --git a/.agents/skills/api-doc/SKILL.md b/.agents/skills/api-doc/SKILL.md new file mode 100644 index 0000000000..3fce357a74 --- /dev/null +++ b/.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`. diff --git a/.claude/skills/api-doc/references/openapi-patterns.md b/.agents/skills/api-doc/references/openapi-patterns.md similarity index 100% rename from .claude/skills/api-doc/references/openapi-patterns.md rename to .agents/skills/api-doc/references/openapi-patterns.md diff --git a/.agents/skills/api-doc/references/process.md b/.agents/skills/api-doc/references/process.md new file mode 100644 index 0000000000..5673e3873c --- /dev/null +++ b/.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. diff --git a/.agents/skills/doc-write/SKILL.md b/.agents/skills/doc-write/SKILL.md new file mode 100644 index 0000000000..19242b2798 --- /dev/null +++ b/.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`. diff --git a/.claude/skills/doc-write/references/doc-structures.md b/.agents/skills/doc-write/references/doc-structures.md similarity index 100% rename from .claude/skills/doc-write/references/doc-structures.md rename to .agents/skills/doc-write/references/doc-structures.md diff --git a/.agents/skills/doc-write/references/process.md b/.agents/skills/doc-write/references/process.md new file mode 100644 index 0000000000..3c5a968723 --- /dev/null +++ b/.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 "" --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. diff --git a/.agents/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md new file mode 100644 index 0000000000..4ac2c9a537 --- /dev/null +++ b/.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 "" --minAlertLevel=error` (prose style, pronouns, dashes, code fences, admonitions) + - `scripts/check-frontmatter.sh ""` (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`. diff --git a/.agents/skills/review-docs/references/process.md b/.agents/skills/review-docs/references/process.md new file mode 100644 index 0000000000..62973d5928 --- /dev/null +++ b/.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 ` 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 "" --minAlertLevel=error` (prose style, dashes, code fences, admonitions) +- `scripts/check-frontmatter.sh ""` (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. diff --git a/.claude/skills/review-docs/references/review-format.md b/.agents/skills/review-docs/references/review-format.md similarity index 100% rename from .claude/skills/review-docs/references/review-format.md rename to .agents/skills/review-docs/references/review-format.md diff --git a/.agents/skills/review-docs/scripts/check-frontmatter.sh b/.agents/skills/review-docs/scripts/check-frontmatter.sh new file mode 100755 index 0000000000..0d326e3cd0 --- /dev/null +++ b/.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 + +set -euo pipefail + +if [ $# -ne 1 ]; then + echo "Usage: $0 " + 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 diff --git a/.agents/skills/tutorial/SKILL.md b/.agents/skills/tutorial/SKILL.md new file mode 100644 index 0000000000..75a9955112 --- /dev/null +++ b/.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`. diff --git a/.agents/skills/tutorial/references/process.md b/.agents/skills/tutorial/references/process.md new file mode 100644 index 0000000000..4b467d1c32 --- /dev/null +++ b/.agents/skills/tutorial/references/process.md @@ -0,0 +1,63 @@ +# Tutorial creation process + +Agent-agnostic workflow for creating structured Apify tutorials. + +## Step 1: Determine tutorial type + +- **Platform tutorial** - How to use Apify platform features (`sources/platform/`) +- **Academy tutorial** - Teaching web scraping or automation concepts (`sources/academy/tutorials/`) +- **Integration tutorial** - Connecting Apify with other tools (`sources/platform/integrations/`) + +## Step 2: Research + +- Read related docs to understand the topic +- Check existing tutorials for style reference +- Identify prerequisites the reader needs + +## Step 3: Create front matter + +```yaml +--- +title: Action-oriented title in sentence case +description: Value-focused description, 140-160 characters +sidebar_position: 1.0 +slug: /category/tutorial-name +--- +``` + +Use simple present tense ("Create an Actor" not "Creating an Actor"). Match slug to file path. + +## Step 4: Write tutorial content + +Follow the 8-section template in `references/tutorial-template.md`: + +1. Introduction with learning objectives +1. Prerequisites with checklist and time estimate +1. Step-by-step instructions (numbered, action verbs) +1. Code examples (complete, runnable, with code tabs) +1. Testing/verification with expected output +1. Troubleshooting for common issues +1. Summary of accomplishments +1. Next steps with links + +Each step should have a clear action verb, expected result, and verification. Code examples must be complete - no pseudocode. + +## Step 5: Quality check + +- Run `npm run lint:md` on the new file +- Run `vale "" --minAlertLevel=error` +- Run `npm start` (or `npm run build`) to verify no broken links or slug conflicts + +## Edge cases + +### Build fails after adding tutorial + +Verify front matter has all required fields. Run `npm run build` to catch broken links and slug issues. + +### Code examples don't render correctly + +Ensure every code block has a language specifier. For code tabs, use the exact Docusaurus `Tabs`/`TabItem` import pattern from `references/tutorial-template.md`. + +### Tutorial doesn't appear in sidebar + +Add `sidebar_position` and verify the file is in the correct `sources/` subdirectory. diff --git a/.claude/skills/tutorial/references/tutorial-template.md b/.agents/skills/tutorial/references/tutorial-template.md similarity index 100% rename from .claude/skills/tutorial/references/tutorial-template.md rename to .agents/skills/tutorial/references/tutorial-template.md diff --git a/.claude/README.md b/.claude/README.md index 75ed21964d..8baf8ba647 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -5,30 +5,36 @@ This directory contains Claude Code configuration for the Apify documentation re ## Structure ```text -.claude/ -├── README.md # This file - Quick start guide -├── instructions.md # Main instructions for Claude Code -├── rules/ # Canonical standards (auto-loaded) -│ ├── writing-style.md # Prose voice and tone -│ ├── content-standards.md # Formatting and structure -│ ├── terminology.md # Product names and capitalization -│ ├── file-organization.md # Naming conventions -│ ├── grammar-rules.md # Grammar mechanics, punctuation, numbers, brand spelling -│ └── quality-standards.md # Quality checklist -└── skills/ # Reusable skills for common tasks - ├── doc-write/ # Documentation writing skill - ├── api-doc/ # API documentation skill - ├── tutorial/ # Tutorial creation skill - └── review-docs/ # Documentation review skill +.agents/skills/ # Canonical skill location (AgentSkills spec) +├── doc-write/ # Documentation writing skill +├── api-doc/ # API documentation skill +├── tutorial/ # Tutorial creation skill +└── review-docs/ # Documentation review skill + +.claude/skills/ # Symlinks to .agents/skills/ (Claude Code discovery) +├── doc-write -> ../../.agents/skills/doc-write +├── api-doc -> ../../.agents/skills/api-doc +├── tutorial -> ../../.agents/skills/tutorial +└── review-docs -> ../../.agents/skills/review-docs ``` +Skills live in `.agents/skills/` (the AgentSkills open standard path), discoverable by Codex, Gemini CLI, OpenCode, Cursor, and others. Claude Code discovers them via symlinks in `.claude/skills/`. + +Standards live at the repo root (shared across all skills): + +```text +standards/ # Writing, formatting, terminology rules +``` + +Each skill contains its own `references/` and `scripts/` (formerly in `workflows/`). + ## How to use ### For Claude Code users -1. **Start a new session**: Claude Code will automatically read `instructions.md` -2. **Use skills**: Type `/doc-write`, `/api-doc`, `/tutorial`, or `/review-docs` to use specific skills -3. **Reference standards**: Always refer to `AGENTS.md` in the repo root for core standards +1. **Start a new session**: Claude Code reads `CLAUDE.md` (symlink to `AGENTS.md`) +2. **Use skills**: Type `/doc-write`, `/api-doc`, `/tutorial`, or `/review-docs` +3. **Reference standards**: See `standards/` for detailed rules, `AGENTS.md` for summary ### Available skills @@ -72,7 +78,7 @@ Use /review-docs skill to review sources/platform/[file-name].md ## Documentation standards -All documentation standards are in `.claude/rules/` (auto-loaded): +All documentation standards are in `standards/` at the repo root: 1. **`writing-style.md`** - Prose voice and tone 1. **`content-standards.md`** - Formatting and structure @@ -83,9 +89,8 @@ All documentation standards are in `.claude/rules/` (auto-loaded): Also reference: -- **`AGENTS.md`** - Vendor-agnostic documentation standards (in repo root) +- **`AGENTS.md`** - Condensed summary + pointers (in repo root) - **`CONTRIBUTING.md`** - Setup, workflows, contribution process -- **`instructions.md`** - Full Claude Code instructions (in this directory) ## Testing @@ -102,14 +107,14 @@ npm start # Preview changes ## Best practices 1. **Read `CLAUDE.md` first** -2. **Check `.claude/rules/`** - Auto-loaded standards for writing, formatting, terminology +2. **Check `standards/`** - Detailed rules for writing, formatting, terminology 3. **Use the appropriate skill** - Designed for specific documentation tasks 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? -- Questions about style: Check `AGENTS.md` +- Questions about style: Check `standards/` or `AGENTS.md` - Setup issues: See `CONTRIBUTING.md` - Skill usage: Read the specific skill file - Claude Code general: Visit [Claude Code docs](https://github.com/anthropics/claude-code) diff --git a/.claude/claude.json b/.claude/claude.json deleted file mode 100644 index bb46efb7ee..0000000000 --- a/.claude/claude.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "instructions": "instructions.md", - "context": [ - "../CONTRIBUTING.md" - ] -} diff --git a/.claude/instructions.md b/.claude/instructions.md deleted file mode 100644 index b58f01dabc..0000000000 --- a/.claude/instructions.md +++ /dev/null @@ -1,28 +0,0 @@ -# Claude Code instructions for Apify documentation - -`CLAUDE.md` (symlink to `AGENTS.md`) covers project architecture, commands, and common pitfalls. Documentation standards are auto-loaded from `.claude/rules/` - those are the canonical source for all writing, formatting, and terminology rules. - -## Available skills - -| Skill | When to use | -|---|---| -| `/doc-write` | Creating or editing documentation pages | -| `/api-doc` | Working with OpenAPI specifications | -| `/tutorial` | Creating step-by-step tutorials | -| `/review-docs` | Reviewing documentation before submission | - -## PR title format - -Use [Conventional Commits](https://www.conventionalcommits.org/) - enforced by CI: - -- `docs: ` - Documentation changes (most common) -- `fix: ` - Bug fixes -- `feat: ` - New features -- `chore: ` - Maintenance tasks - -## Key reminders - -- Never make assumptions about product features - ask if unsure -- For code review: check comments and obvious mistakes only (not full code review) -- Prioritize clarity and usefulness over strict rule adherence -- See `CONTRIBUTING.md` for development setup and contribution workflow diff --git a/.claude/skills/api-doc b/.claude/skills/api-doc new file mode 120000 index 0000000000..76ff98b6fd --- /dev/null +++ b/.claude/skills/api-doc @@ -0,0 +1 @@ +../../.agents/skills/api-doc \ No newline at end of file diff --git a/.claude/skills/api-doc/SKILL.md b/.claude/skills/api-doc/SKILL.md deleted file mode 100644 index c37b4feddc..0000000000 --- a/.claude/skills/api-doc/SKILL.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -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 -allowed-tools: Read, Write, Edit, Bash, Glob, Grep ---- - -# API documentation - -Create or update OpenAPI specifications and API documentation for Apify API endpoints. - -## Instructions - -### Step 1: Identify the 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 - -For detailed patterns and examples, see `references/openapi-patterns.md`. - -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 -``` - -### Step 6: Quality checks - -- [ ] OpenAPI spec validates without errors -- [ ] Operation IDs follow `objectName_method` convention -- [ ] All parameters have clear descriptions -- [ ] Response schemas are complete with examples -- [ ] Code samples included (JavaScript + Python) -- [ ] Examples use realistic data (not placeholder values) -- [ ] Path references added to main `openapi.yaml` -- [ ] All error responses documented (401, 404, etc.) -- [ ] Authentication requirements documented - -## Examples - -Example 1: Add a new endpoint - -User says: "Add GET endpoint for /request-queues/{queueId}/stats" - -Actions: -1. Create `paths/request-queues/request-queues@{queueId}@stats.yaml` -1. Define GET operation with `operationId: requestQueueStats_get` -1. Add response schema in `components/schemas/RequestQueueStats.yaml` -1. Create code samples in `code_samples/javascript/` and `code_samples/curl/` -1. Register path in `openapi.yaml` -1. Run `npm run openapi:lint` to validate - -Example 2: Add code samples for existing endpoint - -User says: "Add JavaScript code sample for the actorRun_get endpoint" - -Actions: -1. Create `code_samples/javascript/actorRun_get.js` -1. Write realistic example using `ApifyClient` -1. Decorator auto-detects and adds `x-codeSamples` property on build -1. Run `npm run api:rebuild` to verify - -## Troubleshooting - -### OpenAPI validation fails - -Cause: Invalid YAML syntax, missing `$ref` targets, or schema violations. - -Solution: 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 - -Cause: Filename doesn't match `operationId`, or file is in wrong directory. - -Solution: 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 - -Cause: Need to regenerate after editing OpenAPI source files. - -Solution: Run `npm run api:rebuild` to clean and regenerate. The files in `apify-api/docs/` are gitignored and regenerated on every build. - -### Operation ID naming confusion - -Solution: Use `{objectName}_{httpMethod}` pattern. Singular for specific resources (`requestQueue_get`), plural for collections (`requestQueues_get`). See `references/openapi-patterns.md` for full examples. - -## Output - -Provide complete OpenAPI specification changes with proper formatting, ready to be tested and committed. diff --git a/.claude/skills/doc-write b/.claude/skills/doc-write new file mode 120000 index 0000000000..3a4ed1a144 --- /dev/null +++ b/.claude/skills/doc-write @@ -0,0 +1 @@ +../../.agents/skills/doc-write \ No newline at end of file diff --git a/.claude/skills/doc-write/SKILL.md b/.claude/skills/doc-write/SKILL.md deleted file mode 100644 index ffbb265313..0000000000 --- a/.claude/skills/doc-write/SKILL.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -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 -allowed-tools: Read, Write, Edit, Bash, Glob, Grep ---- - -# Documentation writer - -Write or edit Apify documentation following the established style guide and best practices. - -## Instructions - -### 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 `/tutorial` skill instead | - -For tutorials, use the `/tutorial` skill which has a dedicated 8-section structure. - -### Step 2: Create front matter - -```yaml ---- -title: Sentence case title -description: 140-160 character value-focused description -sidebar_position: 1.0 -slug: /path/to/page ---- -``` - -### Step 3: Write content following type structure - -See `references/doc-structures.md` for detailed templates per documentation type. - -**Platform documentation**: Introduction → When to use → How to configure/use → Best practices → Related features - -**Guides**: Introduction → Prerequisites → Step-by-step → Code examples → Testing → Summary - -**Reference**: Overview → Parameters/options → Examples → Related information - -### Step 4: Apply quality standards - -All standards from `.claude/rules/` apply. Key doc-write checks: - -- [ ] Structure matches documentation type -- [ ] Introduction clearly states what the user will learn -- [ ] Prerequisites listed if needed -- [ ] Code examples are complete and tested -- [ ] 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`. - -## Examples - -Example 1: New feature documentation - -User says: "Write docs for the new standby mode feature" - -Actions: -1. Create file at `sources/platform/actors/standby-mode.md` -1. Use platform documentation structure -1. Write introduction explaining what standby mode is and when to use it -1. Add configuration steps with code examples -1. Include best practices and link to related Actor docs - -Result: Complete platform doc page ready for review. - -Example 2: Edit existing page - -User says: "Update the storage docs to include the new retention policy" - -Actions: -1. Read existing file to understand current structure -1. Add new section following existing patterns -1. Ensure new content matches style guide -1. Verify no broken links or heading hierarchy issues - -Result: Updated page with new section, preserving existing structure. - -## Troubleshooting - -### Description too short or too long - -Cause: Front matter `description` must be 140-160 characters for SEO. - -Solution: Focus on user value, not feature lists. Use active language. Count characters and adjust. Example: "Learn how to store and manage data in Apify datasets, key-value stores, and request queues for your Actors." (112 chars - too short, expand with more value). - -### Heading hierarchy warnings from markdownlint - -Cause: Skipped heading levels (e.g., H2 → H4) or multiple H1 tags. - -Solution: H1 comes from front matter `title`. Start page content with H2, then H3 for subsections. Never skip levels. - -### Page doesn't match existing documentation patterns - -Cause: New page uses different structure than sibling pages. - -Solution: Before writing, read 2-3 existing pages in the same directory to match patterns. Check heading structure, code example style, and admonition usage. - -## Output - -Provide complete documentation with proper formatting, ready to be committed to the repository. diff --git a/.claude/skills/review-docs b/.claude/skills/review-docs new file mode 120000 index 0000000000..8d8fe1a931 --- /dev/null +++ b/.claude/skills/review-docs @@ -0,0 +1 @@ +../../.agents/skills/review-docs \ No newline at end of file diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md deleted file mode 100644 index ff4b114198..0000000000 --- a/.claude/skills/review-docs/SKILL.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -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, Agent ---- - -# Documentation review - -Review documentation for compliance with Apify style guide, quality standards, and best practices. - -## Instructions - -### Step 1: Check latest changes - -**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 ` to ensure the branch is current - -## Standards reference - -Review compliance against all standards in `.claude/rules/`: - -- `writing-style.md` - Prose voice and tone -- `content-standards.md` - Formatting and structure -- `terminology.md` - Product names and capitalization -- `grammar-rules.md` - Grammar mechanics and punctuation -- `quality-standards.md` - Complete quality checklist -- `file-organization.md` - File naming and directory structure - -## Review process - -### Step 2: Run automated checks - -```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 - -### Style compliance (delegated) - -For each rules file, launch a subagent to check the reviewed content against that file's standards. The subagent reads the rules file directly, so the review always uses the latest rules. - -Check content compliance against: - -1. `writing-style.md` - voice, tone, language patterns -1. `content-standards.md` - formatting, front matter, headings, code, links, images -1. `terminology.md` - product names, article usage, feature terms -1. `grammar-rules.md` - hyphenation, punctuation, numbers, brand spelling - -Each subagent should return a list of violations with line numbers and suggested fixes. - -### Content review (manual) - -These aspects require judgment and aren't covered by the rules files: - -- [ ] **Content structure** - Clear introduction, logical progression, summary/next steps -- [ ] **Heading hierarchy** - H2 → H3 → H4, no skipped levels -- [ ] **Technical accuracy** - Code examples tested, API endpoints current, no deprecated features -- [ ] **Completeness** - Prerequisites listed, all steps included, edge cases addressed -- [ ] **Content-type checks** - - **Tutorials**: Clear learning objectives, sequential numbered steps, verification at each step - - **API docs**: All parameters documented, code samples in JS and Python, error responses - - **Reference pages**: Comprehensive parameter tables, default values, type information -- [ ] **Accessibility** - Proper heading hierarchy, descriptive link text, image alt text -- [ ] **SEO** - Descriptive title, meta description 140-160 chars, internal linking - -## Examples - -Example 1: Pre-PR review - -User says: "Review sources/platform/actors/running.md before I submit" - -Actions: -1. Read the file -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 - -Example 2: Style audit - -User says: "Check if this page follows the style guide" - -Actions: -1. Read the file -1. Focus on writing quality and terminology checks -1. Flag specific lines with issues and suggested fixes -1. Provide priority ranking - -## Troubleshooting - -### Markdownlint reports false positives on admonitions - -Cause: Markdownlint doesn't understand Docusaurus `:::` admonition syntax natively. - -Solution: Check `.markdownlint.json` for configured exceptions. Some rules (like MD046) may be disabled for admonition blocks. Focus on Vale for prose quality instead. - -### Vale reports errors on Apify product names - -Cause: Vale styles may not include Apify-specific terminology. - -Solution: Check `.vale/styles/` for Apify vocabulary files. If missing, run `vale sync` to download the latest styles. Product names like "Actor", "Console", "Proxy" are correct as capitalized. - -### Unsure if a term should be capitalized - -Solution: Check `.claude/rules/terminology.md` for the definitive list. Product names (Actor, Console, Proxy, Store) are capitalized. Feature terms (task, schedule, dataset) are lowercase. - -## Output - -Provide a structured review using the format in `references/review-format.md`, with clear identification of issues, specific examples, concrete suggestions, and priority ranking. diff --git a/.claude/skills/tutorial b/.claude/skills/tutorial new file mode 120000 index 0000000000..84724d107a --- /dev/null +++ b/.claude/skills/tutorial @@ -0,0 +1 @@ +../../.agents/skills/tutorial \ No newline at end of file diff --git a/.claude/skills/tutorial/SKILL.md b/.claude/skills/tutorial/SKILL.md deleted file mode 100644 index 8c86b6124b..0000000000 --- a/.claude/skills/tutorial/SKILL.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -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. -argument-hint: topic -allowed-tools: Read, Write, Edit, Bash, Glob, Grep ---- - -# Tutorial creator - -Create comprehensive, structured tutorials for Apify documentation following the 8-section template. - -## Instructions - -### Step 1: Determine tutorial type - -Identify the tutorial type based on user request: - -- **Platform tutorial** - How to use Apify platform features (`sources/platform/`) -- **Academy tutorial** - Teaching web scraping or automation concepts (`sources/academy/tutorials/`) -- **Integration tutorial** - Connecting Apify with other tools (`sources/platform/integrations/`) - -### Step 2: Create front matter - -```yaml ---- -title: Action-oriented title in sentence case -description: Value-focused description, 140-160 characters -sidebar_position: 1.0 -slug: /category/tutorial-name ---- -``` - -Use simple present tense ("Create an Actor" not "Creating an Actor"). Match slug to file path. - -### Step 3: Write tutorial content - -Follow the 8-section template in `references/tutorial-template.md`: - -1. Introduction with learning objectives -1. Prerequisites with checklist and time estimate -1. Step-by-step instructions (numbered, action verbs) -1. Code examples (complete, runnable, with code tabs) -1. Testing/verification with expected output -1. Troubleshooting for common issues -1. Summary of accomplishments -1. Next steps with links - -### Step 4: Apply quality standards - -All standards from `.claude/rules/` apply. Key tutorial-specific checks: - -- [ ] Clear learning objectives in introduction -- [ ] Prerequisites listed with time estimate -- [ ] Steps are numbered and start with action verbs -- [ ] Code examples are complete, tested, and runnable -- [ ] Expected results shown after each major step -- [ ] 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`. - -## Examples - -Example 1: Platform tutorial request - -User says: "Create a tutorial for deploying an Actor to production" - -Actions: -1. Create file at `sources/platform/actors/tutorials/deploy-actor.md` -1. Use platform tutorial structure from template -1. Include prerequisites (Apify account, Actor ready) -1. Write step-by-step deployment instructions with screenshots -1. Add code examples for `apify push` and Console deployment -1. Include troubleshooting for common deployment errors - -Result: Complete tutorial following 8-section template, ready for review. - -Example 2: Academy tutorial request - -User says: "Write a tutorial on web scraping with Playwright" - -Actions: -1. Create file at `sources/academy/tutorials/playwright-scraping.md` -1. Use academy tutorial structure (educational, concept-focused) -1. Include prerequisites (Node.js, basic JavaScript) -1. Teach concepts progressively with working code at each step -1. Include both JavaScript and Python code tabs - -Result: Educational tutorial with progressive learning structure. - -## Troubleshooting - -### Build fails after adding tutorial - -Cause: Missing or incorrect front matter (slug mismatch, missing description). - -Solution: Verify front matter has all required fields. Run `npm run build` to catch broken links and slug issues. Check that `onBrokenLinks` errors reference your new file. - -### Code examples don't render correctly - -Cause: Missing language tag on code blocks or incorrect code tab syntax. - -Solution: Ensure every code block has a language specifier. For code tabs, use the exact Docusaurus `Tabs`/`TabItem` import pattern from `references/tutorial-template.md`. - -### Tutorial doesn't appear in sidebar - -Cause: Missing `sidebar_position` in front matter or file in wrong directory. - -Solution: Add `sidebar_position` and verify the file is in the correct `sources/` subdirectory. Check `sidebars.js` if using manual sidebar configuration. - -## Output - -Provide a complete tutorial following the 8-section template, ready to be committed to the repository. diff --git a/.cursor/rules/api-documentation.mdc b/.cursor/rules/api-documentation.mdc index 2086f69a60..d2de63bdc0 100644 --- a/.cursor/rules/api-documentation.mdc +++ b/.cursor/rules/api-documentation.mdc @@ -1,62 +1,7 @@ --- -description: Cursor-specific rules for OpenAPI specifications and API documentation +description: API documentation standards for OpenAPI specifications globs: ["apify-api/**/*.yaml", "apify-api/**/*.js"] alwaysApply: true --- - -# Cursor-Specific API Documentation Rules - -## Cursor OpenAPI Workflow - -### Using Cursor for OpenAPI Editing - -- Leverage Cursor's YAML syntax highlighting for OpenAPI files -- Use Cursor's JSON schema validation for OpenAPI specifications -- Use Cursor's autocomplete for OpenAPI keywords and properties - -### Cursor-Specific API Documentation Tasks - -- Use Cursor Chat to "validate this OpenAPI specification" -- Ask "generate code examples for this endpoint" -- Request "check for consistency across similar endpoints" - -## Cursor Code Sample Generation - -### Using Cmd+K for API References - -- Use `@apify-api/openapi/paths/**/*.yaml` to reference endpoint definitions -- Use `@apify-api/openapi/components/schemas/**/*.yaml` to reference data models -- Use `@AGENTS.md` to reference API documentation standards - -### Cursor-Specific Code Sample Workflow - -```yaml -# When editing OpenAPI files in Cursor: -# 1. Use Cursor's YAML validation -# 2. Leverage autocomplete for OpenAPI keywords -# 3. Use Cursor Chat to generate examples -# 4. Use Cursor's search to find similar patterns -``` - -## File-Specific Cursor Rules - -### For OpenAPI Specification Files (`apify-api/openapi/**/*.yaml`) - -- Use Cursor's YAML syntax highlighting and validation -- Leverage Cursor's autocomplete for OpenAPI 3.0 keywords -- Use Cursor's search to find similar endpoint patterns -- Use Cursor Chat to validate OpenAPI compliance - -### For Generated Code Samples (`apify-api/openapi/code_samples/**/*.js`) - -- Use Cursor's JavaScript syntax highlighting -- Leverage Cursor's autocomplete for JavaScript APIs -- Use Cursor's search to find similar code patterns -- Use Cursor Chat to improve code examples - -## Cursor Quality Assurance for APIs - -- Use Cursor's YAML validation for OpenAPI files -- Leverage Cursor's search to ensure endpoint naming consistency -- Use Cursor Chat to review API documentation completeness -- Use Cursor's autocomplete to maintain OpenAPI specification standards +For API documentation process and conventions, see `.agents/skills/api-doc/references/process.md`. +For OpenAPI patterns and examples, see `.agents/skills/api-doc/references/openapi-patterns.md`. diff --git a/.cursor/rules/content-formatting.mdc b/.cursor/rules/content-formatting.mdc index 400d9f8d63..a2c49e23a0 100644 --- a/.cursor/rules/content-formatting.mdc +++ b/.cursor/rules/content-formatting.mdc @@ -1,82 +1,7 @@ --- -description: Cursor-specific content formatting rules for MDX and markdown files +description: Content formatting standards for markdown and MDX files globs: ["sources/**/*.md", "sources/**/*.mdx"] alwaysApply: true --- - -# Cursor-Specific Content Formatting - -## Cursor MDX/Markdown Features - -### Syntax Highlighting in Cursor - -- Use language-specific code blocks for proper syntax highlighting -- Leverage Cursor's MDX component autocomplete -- Use Cursor's markdown preview for real-time formatting verification - -### Cursor-Specific Code Block Handling - -```markdown -# For JavaScript examples -```javascript -// Cursor will provide syntax highlighting and autocomplete -const example = "properly formatted"; -``` - -# For YAML frontmatter - -```yaml ---- -title: "Example" -description: "Description" ---- -``` - -# For API examples - -```bash -curl -X GET "https://api.apify.com/v2/acts" -``` - - -## Cursor Workflow for Formatting - -### Using Cursor Chat for Formatting Help - -- Ask "format this markdown table properly" -- Request "add syntax highlighting to this code block" -- Use "check this frontmatter for proper YAML syntax" - -### Using Cmd+K for Quick Formatting - -- Use `@` to reference formatting standards -- Use `@sources/**/*.mdx` to find similar MDX patterns -- Use `@apify-api/**/*.yaml` to reference API examples - -## Cursor-Specific Admonition Handling - -When using admonitions in Cursor: - -```markdown -:::note Cursor Tip -Use Cursor's markdown preview to verify admonition formatting -::: - -:::tip Cursor Feature -Leverage Cursor's autocomplete for consistent admonition syntax -::: -``` - -## File-Specific Formatting Rules - -### For MDX Files (`sources/**/*.mdx`) - -- Use Cursor's MDX syntax highlighting -- Leverage component imports with proper TypeScript support -- Use Cursor's JSX autocomplete for custom components - -### For Markdown Files (`sources/**/*.md`) - -- Use Cursor's markdown preview for formatting verification -- Leverage Cursor's spell check for content quality -- Use Cursor's link validation for internal references +For content formatting rules (front matter, admonitions, code blocks, images, lists), see `standards/content-standards.md`. +For writing style rules (headings, tone, links, numbers), see `standards/writing-style.md`. diff --git a/.cursor/rules/documentation-style.mdc b/.cursor/rules/documentation-style.mdc index 515124052c..ef19b1d5a0 100644 --- a/.cursor/rules/documentation-style.mdc +++ b/.cursor/rules/documentation-style.mdc @@ -1,55 +1,10 @@ --- -description: Cursor-specific documentation style rules for Apify docs +description: Documentation standards and workflow references globs: ["sources/**/*.md", "sources/**/*.mdx"] alwaysApply: true --- - -# Cursor-Specific Documentation Rules - -## Context-Aware Writing - -When editing documentation in Cursor, consider the broader context: - -- **Cross-references**: When mentioning other pages, use Cursor's file navigation to verify links -- **Consistency checks**: Use Cursor's search to ensure terminology consistency across files -- **Code examples**: Leverage Cursor's syntax highlighting and validation for code blocks - -## Cursor-Specific Workflows - -### Using Cursor Chat for Documentation - -- Ask Cursor to "review this documentation for clarity and completeness" -- Use "explain this technical concept in simpler terms" for complex topics -- Request "suggest improvements for this tutorial structure" - -### Using Cmd+K for Quick Edits - -- Use `@AGENTS.md` to reference the main documentation standards -- Use `@sources/**/*.md` to search across all documentation files -- Use `@apify-api/**/*.yaml` to reference API specifications - -## File-Specific Guidance - -### For Platform Documentation (`sources/platform/**/*.md`) - -- Focus on practical, actionable guidance -- Include real-world examples and use cases -- Reference related API endpoints when applicable - -### For Academy Content (`sources/academy/**/*.md`) - -- Structure content for learning progression -- Include hands-on exercises and examples -- Provide clear prerequisites and next steps - -### For MDX Files - -- Leverage Cursor's MDX syntax highlighting -- Use component imports and JSX syntax appropriately -- Ensure proper frontmatter formatting - -## Quality Assurance in Cursor - -- Use Cursor's spell check for documentation files -- Leverage Cursor's markdown preview for formatting verification -- Use Cursor's search to find similar content and maintain consistency +When writing or editing documentation, follow the standards in `standards/`. +When reviewing documentation, follow the process in `.agents/skills/review-docs/references/process.md`. +When writing new pages, follow the process in `.agents/skills/doc-write/references/process.md`. +When creating tutorials, follow the process in `.agents/skills/tutorial/references/process.md`. +When writing API docs, follow the process in `.agents/skills/api-doc/references/process.md`. diff --git a/.cursor/rules/file-organization.mdc b/.cursor/rules/file-organization.mdc deleted file mode 120000 index b434263850..0000000000 --- a/.cursor/rules/file-organization.mdc +++ /dev/null @@ -1 +0,0 @@ -../../.claude/rules/file-organization.md \ No newline at end of file diff --git a/.cursor/rules/quality-standards.mdc b/.cursor/rules/quality-standards.mdc deleted file mode 120000 index a7640b2aa0..0000000000 --- a/.cursor/rules/quality-standards.mdc +++ /dev/null @@ -1 +0,0 @@ -../../.claude/rules/quality-standards.md \ No newline at end of file diff --git a/.cursor/rules/writing-style.mdc b/.cursor/rules/writing-style.mdc deleted file mode 120000 index 502fd404ed..0000000000 --- a/.cursor/rules/writing-style.mdc +++ /dev/null @@ -1 +0,0 @@ -../../.claude/rules/writing-style.md \ No newline at end of file diff --git a/.github/workflows/vale.yaml b/.github/workflows/vale.yaml index 89cbc8fffc..8fb7bf6597 100644 --- a/.github/workflows/vale.yaml +++ b/.github/workflows/vale.yaml @@ -23,8 +23,10 @@ jobs: apify-api/openapi/paths/README.md apify-api/openapi/components/README.md sources/legal/**/*.{md,mdx} - .claude/rules/**/*.{md,mdx} + .claude/**/*.{md,mdx} .cursor/rules/**/*.{md,mdx} + standards/**/*.{md,mdx} + workflows/**/*.{md,mdx} separator: ',' - uses: errata-ai/vale-action@reviewdog diff --git a/.markdownlintignore b/.markdownlintignore index cdf8464963..08e46a95bc 100644 --- a/.markdownlintignore +++ b/.markdownlintignore @@ -1,6 +1,8 @@ node_modules build .claude +.agents AGENTS.md CLAUDE.md +standards sources/_partials/* diff --git a/.vale.ini b/.vale.ini index b63185ce7a..dd0d3863ab 100644 --- a/.vale.ini +++ b/.vale.ini @@ -36,3 +36,9 @@ Apify.H1 = NO [.claude/**/*.md] # Ignore all Vale checks in .claude directory (infrastructure docs) BasedOnStyles = + +[standards/**/*.md] +BasedOnStyles = + +[.agents/**/*.md] +BasedOnStyles = diff --git a/AGENTS.md b/AGENTS.md index 141f413061..9223bb4cda 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -118,124 +118,35 @@ Use `npm run start:dev` + nginx to serve all repos together locally. See `CONTRI --- -## Writing style +## Standards -### Language and tone +Detailed writing and formatting standards are in `standards/`: -- **US English** spelling (analyze, color, not analyse, colour) -- **Active voice** and **imperative tone** ("Install the package", not "You should install") -- **Simple English** - no sentence over 30 words, get to the point -- **Inclusive language** - avoid gendered terms, don't use directional language (left/right) for UI -- No first person ("I recommend") - use "you" for the reader -- No sales language ("ultimate", "cutting-edge", "supercharge") +- `standards/writing-style.md` - Prose voice, tone, headings, links, numbers +- `standards/content-standards.md` - Front matter, admonitions, code blocks, images +- `standards/terminology.md` - Product names, capitalization, article usage +- `standards/grammar-rules.md` - Hyphenation, punctuation, numbers, brand spelling +- `standards/file-organization.md` - File naming and directory structure +- `standards/quality-standards.md` - Complete quality checklist before submitting -### Headings +Key rules at a glance: -- **Sentence case only** - capitalize first word and proper nouns only -- **No gerunds** (-ing forms) - use noun phrases or imperatives -- **Capitalize after colons** when introducing a complete clause -- **Proper hierarchy** - H1 (from frontmatter) → H2 → H3 → H4, never skip levels +- US English, active voice, imperative tone, no sales language +- Sentence case headings, no gerunds +- Bold for UI elements only; `code` for filenames, commands, variables +- All admonitions require titles +- 140-160 character descriptions in front matter +- See `standards/terminology.md` for Apify product name capitalization +- Don't use em dashes (—) - use hyphen with spaces ( - ) instead -Examples: +## Skills -| Avoid | Prefer | -|---|---| -| Store And Manage Data | Store and manage data | -| Getting Started With Actors | Get started with Actors | -| Step 1: install the dependencies | Step 1: Install the dependencies | +Documentation skills live in `.agents/skills/` ([AgentSkills spec](https://agentskills.io)), each with its own `references/` and `scripts/`: -### Text formatting - -- **Bold** for UI elements only (buttons, menus, fields) and critical warnings -- *Italics* for emphasis and introducing new terms -- `code` for file names, commands, config keys, variables, and code values -- Never use bold for list introductions or general emphasis - -### Admonitions - -All admonitions must have titles (2-3 scannable words). Types: `note`, `tip`, `info`, `caution`, `danger`. - -```markdown -:::note Actor versions -Actors can have multiple versions. Pin to a specific version for production use. -::: -``` - -### Lists - -- Numbered lists (`1.` for all items) for sequential steps -- Bullet points for non-sequential items -- All items must follow the same grammatical pattern (parallel structure) -- Use Oxford commas - -### Links - -- Descriptive, action-oriented link text (never "click here" or "here") -- Internal links use relative paths, never full URLs -- Link external tools to official sites on first mention -- Link Actor names on first mention - -### Em dashes - -Don't use em dashes (—). Use hyphen with spaces ( - ) instead. - -## Content formatting - -### Front matter - -Every `.md`/`.mdx` file requires: - -```yaml ---- -title: Sentence case title -description: 140-160 character description for SEO -sidebar_position: 1.0 -slug: /path/to/page ---- -``` - -### Code examples - -- Complete and runnable -- Syntax highlighting specified for all code blocks -- Code tabs for multi-language examples (JavaScript + Python) -- Version matching between Dockerfile tags and package.json - -### Images - -- Meaningful alt text on all images -- Light theme for screenshots -- Red indicators to highlight UI elements -- Store in `images/` subdirectory next to the markdown file -- PNG for screenshots, SVG for logos - -## Terminology - -### Product names (always capitalize) - -Apify Actor, Apify Proxy, Apify Console, Apify Store, Apify SDK, Apify CLI, Apify API - -### Platform terms (lowercase with "the") - -the Apify platform, the Apify team, the Apify ecosystem - -### Feature terms (always lowercase) - -task, schedule, run, build, dataset, key-value store, request queue, web scraping - -### Generic technical terms (lowercase) - -AI agent, MCP server, API endpoint, web scraper, proxy server - -### Actor references - -First mention: full name with link (`[Website Content Crawler](https://apify.com/apify/website-content-crawler)`). Subsequent mentions: just the name. - -## File organization - -- **Kebab-case** for file names: `web-scraping-basics.md` -- Match slug to file path -- Group related files in logical directories +- `.agents/skills/review-docs/` - Documentation review process and output format +- `.agents/skills/doc-write/` - Writing and editing documentation pages +- `.agents/skills/tutorial/` - Creating structured tutorials +- `.agents/skills/api-doc/` - OpenAPI specification and API documentation ## Review checklist diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9e4b26ad82..1b40f13f99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,45 +128,31 @@ You should be able to open https://docs.apify.loc in your browser and run all th - Avoid repetitive keywords - Avoid the word "documentation" in descriptions -## AI Assistant rules structure +## AI assistant rules structure -This project uses a hybrid approach for AI assistant rules to ensure consistency across different tools while leveraging Cursor-specific features. +This project uses an agent-agnostic approach: standards and workflows live at the repo root, with thin adapter files for each AI tool. -### Structure overview +### Source of truth -#### Vendor-agnostic rules +- **`standards/`** - Writing, formatting, terminology, and quality rules +- **`.agents/skills/`** - Documentation skills with processes, references, and scripts (AgentSkills spec) +- **`AGENTS.md`** - Condensed summary + pointers (also `CLAUDE.md` via symlink) -- **`AGENTS.md`** - Primary vendor-agnostic rules file containing core documentation standards +### Skills (AgentSkills standard) -#### Cursor-specific rules +- **`.agents/skills/`** - Skill definitions following the [AgentSkills spec](https://agentskills.io) (discoverable by Codex, Gemini CLI, OpenCode, Cursor, and others) +- **`.claude/skills/`** - Symlinks to `.agents/skills/` for Claude Code discovery -- **`.cursor/rules/documentation-style.mdc`** - Cursor-specific documentation guidelines -- **`.cursor/rules/content-formatting.mdc`** - Cursor-specific formatting rules -- **`.cursor/rules/api-documentation.mdc`** - Cursor-specific API documentation rules -- **`.cursor/rules/quality-standards.mdc`** - Cursor-specific quality guidelines -- **`.cursor/rules/file-organization.mdc`** - Cursor-specific file organization rules +### Agent-specific adapters -To verify rule application, hover over attached rules in the Cursor chat window. +- **`.cursor/rules/`** - Thin pointers to `standards/` for Cursor ### Usage -#### For general AI assistants - -- Reference `AGENTS.md` for vendor-agnostic documentation standards - -#### For Cursor-specific features - -- Use `.cursor/rules/*.mdc` files for Cursor-specific workflows -- Leverage glob patterns and `alwaysApply` settings -- Use Cursor Chat and Cmd+K with `@AGENTS.md` references - -### File targeting - -Each `.mdc` file uses glob patterns to target specific file types: - -- **`documentation-style.mdc`**: `["sources/**/*.md", "sources/**/*.mdx"]` -- **`content-formatting.mdc`**: `["sources/**/*.md", "sources/**/*.mdx"]` -- **`api-documentation.mdc`**: `["apify-api/**/*.yaml", "apify-api/**/*.js"]` +- Any AI assistant can follow `AGENTS.md` and read `standards/` directly +- Skills-compatible agents (Claude Code, Codex, Gemini CLI, OpenCode, Cursor): discover skills from `.agents/skills/` +- Claude Code users: use `/doc-write`, `/api-doc`, `/tutorial`, `/review-docs` skills +- Cursor users: rules auto-load via glob patterns on `sources/**/*.md` files ## Repository structure diff --git a/.claude/rules/content-standards.md b/standards/content-standards.md similarity index 91% rename from .claude/rules/content-standards.md rename to standards/content-standards.md index 01e8c04e74..96fe76cecc 100644 --- a/.claude/rules/content-standards.md +++ b/standards/content-standards.md @@ -62,6 +62,10 @@ Follow proper heading hierarchy: H2 → H3 → H4. Never skip levels. (H1 is the #### Detail (H4 - use sparingly) ``` +## Information ordering + +Order sections so no concept is used before it's explained. Treat information dependencies as a directed graph - if understanding B requires A, present A first. When restructuring or reviewing a page, check that each section only relies on concepts introduced earlier on the page or linked to explicitly. + ## Admonitions Use Docusaurus admonitions for important information. **All admonitions MUST have titles.** @@ -84,25 +88,7 @@ Content of the admonition. ::: ``` -### Examples - -```markdown -:::note Actor versions -Actors can have multiple versions. Pin to a specific version for production use. -::: - -:::tip Performance optimization -Use the `maxRequestsPerCrawl` option to limit the number of requests for testing. -::: - -:::caution Breaking changes -Version 3.0 introduces breaking changes. Review the migration guide before upgrading. -::: - -:::danger Data loss risk -Deleting a dataset is permanent. All data will be lost and cannot be recovered. -::: -``` +> Missing titles enforced by Vale (`Apify.AdmonitionTitle`). Run `vale ""` to check. ## Code examples diff --git a/.claude/rules/file-organization.md b/standards/file-organization.md similarity index 100% rename from .claude/rules/file-organization.md rename to standards/file-organization.md diff --git a/.claude/rules/grammar-rules.md b/standards/grammar-rules.md similarity index 92% rename from .claude/rules/grammar-rules.md rename to standards/grammar-rules.md index d3d36f79ca..1984425e50 100644 --- a/.claude/rules/grammar-rules.md +++ b/standards/grammar-rules.md @@ -151,19 +151,6 @@ Use "they/their" as a singular pronoun when the person's name isn't specified. ## Tool and brand name spelling -Use the exact official spelling for tools and brand names: - -| Incorrect | Correct | -|-----------|---------| -| Javascript | JavaScript | -| Typescript | TypeScript | -| NodeJS, Node.JS | Node.js | -| Github | GitHub | -| Chatgpt | ChatGPT | -| N8n, N8N | n8n | -| Mongodb | MongoDB | -| Postgresql, Postgres | PostgreSQL | -| Jquery | jQuery | -| Wordpress | WordPress | -| VSCode, VS code | VS Code | -| DockerFile, dockerfile | Dockerfile | +Use the exact official spelling for tools and brand names (JavaScript, TypeScript, Node.js, GitHub, ChatGPT, MongoDB, PostgreSQL, VS Code, WordPress, n8n, LangChain, jQuery, Dockerfile). + +> Enforced by Vale (`Apify.Languages`). Run `vale ""` to check. diff --git a/.claude/rules/quality-standards.md b/standards/quality-standards.md similarity index 85% rename from .claude/rules/quality-standards.md rename to standards/quality-standards.md index 4984328c83..fc1896b99b 100644 --- a/.claude/rules/quality-standards.md +++ b/standards/quality-standards.md @@ -100,33 +100,19 @@ Before submitting documentation, verify: ### For documentation pages -Use the **doc-write** skill for comprehensive guidance on: -- Content structure (introduction, prerequisites, steps, examples, summary) -- Documentation type distinction (tutorials vs guides vs reference) -- Platform-specific or Academy-specific requirements +Follow the writing process in `.agents/skills/doc-write/references/process.md`. See `.agents/skills/doc-write/references/doc-structures.md` for content type templates. ### For tutorials -Use the **tutorial** skill for comprehensive guidance on: -- Tutorial structure template (8-section format) -- Learning objectives and expected outcomes -- Step-by-step instructions with verification -- Troubleshooting section +Follow the tutorial process in `.agents/skills/tutorial/references/process.md`. See `.agents/skills/tutorial/references/tutorial-template.md` for the 8-section structure. ### For API documentation -Use the **api-doc** skill for comprehensive guidance on: -- OpenAPI specification standards -- Operation ID conventions -- Code sample requirements (JavaScript and Python) -- Schema and path documentation +Follow the API documentation process in `.agents/skills/api-doc/references/process.md`. See `.agents/skills/api-doc/references/openapi-patterns.md` for OpenAPI conventions. ### For documentation review -Use the **review-docs** skill for comprehensive guidance on: -- Review process and priority ranking -- Common issues and how to fix them -- Output format for review feedback +Follow the review process in `.agents/skills/review-docs/references/process.md`. See `.agents/skills/review-docs/references/review-format.md` for output format. ## Pre-submission checklist diff --git a/.claude/rules/terminology.md b/standards/terminology.md similarity index 100% rename from .claude/rules/terminology.md rename to standards/terminology.md diff --git a/.claude/rules/writing-style.md b/standards/writing-style.md similarity index 93% rename from .claude/rules/writing-style.md rename to standards/writing-style.md index 1e4b820a86..d20c73d8cf 100644 --- a/.claude/rules/writing-style.md +++ b/standards/writing-style.md @@ -53,10 +53,9 @@ Use direct instructions, not soft recommendations: ### No sales language -| Avoid | Prefer | -| ------------------------------------------ | --------------------------------------------------- | -| Experience Apify, the ultimate platform! | Welcome to Apify, the full-stack web scraping platform. | -| Our highly efficient system | Apify's system handles 500K requests per minute | +Don't use promotional terms (ultimate, cutting-edge, supercharge, seamless, etc.). Use factual, specific claims instead. + +> Enforced by Vale (`Apify.SalesLanguage`). Run `vale ""` to check. ### Avoid first person @@ -126,11 +125,7 @@ Acceptable uses of "our" - direct team actions or invitations: **No gerunds (-ing forms).** Use noun phrases or imperatives. -| Avoid | Prefer | -|-------|--------| -| Finding available tags | Available tags | -| Getting started with Actors | Get started with Actors | -| Understanding the API | API overview | +> Enforced by Vale (`Apify.HeadingGerund`). Run `vale ""` to check. ## Text formatting @@ -174,6 +169,8 @@ Use backticks for inline code: Don't use em dashes (—). Use hyphen with spaces ( - ) instead. +> Enforced by Vale (`Microsoft.Dashes`). Run `vale ""` to check. + ## Links ### Descriptive link text @@ -308,5 +305,5 @@ This guide covers writing patterns. For additional rules, see: - `content-standards.md` - Markdown and Docusaurus formatting (front matter, admonitions, code blocks, images, lists) - `grammar-rules.md` - Detailed grammar mechanics (hyphenation, contractions, e.g./i.e., list punctuation) - `terminology.md` - Apify product names, capitalization, and word choice -- [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution workflow and repository standards +- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution workflow and repository standards - Full Apify style guide: https://www.notion.so/apify/Apify-style-guide-1b9f39950a2280d49e5be69ce2961a79