From 4928f93f1bae429b851ad9f83bc43140ec4ca7e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:44:42 +0100 Subject: [PATCH 1/6] chore(vale): add custom rules and enable em dash detection Add deterministic checks for common style violations: missing admonition titles, gerund headings, empty image alt text, and sales language. Extended Languages.yml with GitHub, ChatGPT, MongoDB, PostgreSQL, VS Code, WordPress, n8n, LangChain. Enabled Microsoft.Dashes for em/en dash detection. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/styles/Apify/AdmonitionTitle.yml | 6 ++++++ .github/styles/Apify/HeadingGerund.yml | 14 ++++++++++++++ .github/styles/Apify/ImageAltText.yml | 6 ++++++ .github/styles/Apify/Languages.yml | 9 ++++++++- .github/styles/Apify/SalesLanguage.yml | 15 +++++++++++++++ .vale.ini | 2 +- 6 files changed, 50 insertions(+), 2 deletions(-) create mode 100644 .github/styles/Apify/AdmonitionTitle.yml create mode 100644 .github/styles/Apify/HeadingGerund.yml create mode 100644 .github/styles/Apify/ImageAltText.yml create mode 100644 .github/styles/Apify/SalesLanguage.yml diff --git a/.github/styles/Apify/AdmonitionTitle.yml b/.github/styles/Apify/AdmonitionTitle.yml new file mode 100644 index 0000000000..3fb4503df1 --- /dev/null +++ b/.github/styles/Apify/AdmonitionTitle.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Admonitions must have titles (e.g., ':::note My title')." +level: error +scope: raw +raw: + - ":::(note|tip|info|caution|danger)\\s*\\n" diff --git a/.github/styles/Apify/HeadingGerund.yml b/.github/styles/Apify/HeadingGerund.yml new file mode 100644 index 0000000000..e962131979 --- /dev/null +++ b/.github/styles/Apify/HeadingGerund.yml @@ -0,0 +1,14 @@ +extends: existence +message: "Avoid gerunds (-ing) in headings. Use noun phrases or imperatives." +level: warning +scope: heading +tokens: + - '^\w+ing\b' +exceptions: + - Billing + - Pricing + - Debugging + - String + - Caching + - Logging + - Troubleshooting diff --git a/.github/styles/Apify/ImageAltText.yml b/.github/styles/Apify/ImageAltText.yml new file mode 100644 index 0000000000..634885274f --- /dev/null +++ b/.github/styles/Apify/ImageAltText.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Images must include meaningful alt text." +level: error +scope: raw +raw: + - '!\[\]\(' diff --git a/.github/styles/Apify/Languages.yml b/.github/styles/Apify/Languages.yml index 518584b2fa..d0d4bf5dc6 100644 --- a/.github/styles/Apify/Languages.yml +++ b/.github/styles/Apify/Languages.yml @@ -7,4 +7,11 @@ swap: '(?)|(```.*?```) # Disabling rules (NO) Vale.Spelling = NO write-good.ThereIs = NO -Microsoft.Dashes = NO +Microsoft.Dashes = YES Microsoft.Avoid = NO Microsoft.Contractions = NO Microsoft.Foreign = NO From 97932c269b9cee95668f1cfd1e180911db630f0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 24 Mar 2026 14:01:33 +0100 Subject: [PATCH 2/6] chore: relocate standards to agent-agnostic location Move .claude/rules/ to standards/ at repo root so all agents have parity. Replace verbose style sections in AGENTS.md with condensed summary + pointers. Trim standards where Vale now enforces the check. Add information ordering principle. Update symlinks, supporting files, and lint ignores. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/README.md | 31 ++-- .claude/instructions.md | 2 +- .cursor/rules/file-organization.mdc | 2 +- .cursor/rules/quality-standards.mdc | 2 +- .cursor/rules/writing-style.mdc | 2 +- .github/workflows/vale.yaml | 4 +- .markdownlintignore | 2 + .vale.ini | 6 + AGENTS.md | 138 +++--------------- CONTRIBUTING.md | 43 ++---- .../rules => standards}/content-standards.md | 24 +-- .../rules => standards}/file-organization.md | 0 {.claude/rules => standards}/grammar-rules.md | 19 +-- .../rules => standards}/quality-standards.md | 22 +-- {.claude/rules => standards}/terminology.md | 0 {.claude/rules => standards}/writing-style.md | 17 +-- 16 files changed, 81 insertions(+), 233 deletions(-) rename {.claude/rules => standards}/content-standards.md (91%) rename {.claude/rules => standards}/file-organization.md (100%) rename {.claude/rules => standards}/grammar-rules.md (92%) rename {.claude/rules => standards}/quality-standards.md (85%) rename {.claude/rules => standards}/terminology.md (100%) rename {.claude/rules => standards}/writing-style.md (93%) diff --git a/.claude/README.md b/.claude/README.md index 75ed21964d..37360dc78e 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -8,27 +8,27 @@ This directory contains Claude Code configuration for the Apify documentation re .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 +└── skills/ # Summary + pointer adapters for common tasks ├── doc-write/ # Documentation writing skill ├── api-doc/ # API documentation skill ├── tutorial/ # Tutorial creation skill └── review-docs/ # Documentation review skill ``` +Standards and workflows live at the repo root (agent-agnostic): + +```text +standards/ # Writing, formatting, terminology rules +workflows/ # Reusable processes for doc tasks +``` + ## 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 +72,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 +83,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 +101,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/instructions.md b/.claude/instructions.md index b58f01dabc..b131837191 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -1,6 +1,6 @@ # 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. +`CLAUDE.md` (symlink to `AGENTS.md`) covers project architecture, commands, and common pitfalls. Documentation standards live in `standards/` at the repo root. Workflow processes live in `workflows/`. ## Available skills diff --git a/.cursor/rules/file-organization.mdc b/.cursor/rules/file-organization.mdc index b434263850..c939501367 120000 --- a/.cursor/rules/file-organization.mdc +++ b/.cursor/rules/file-organization.mdc @@ -1 +1 @@ -../../.claude/rules/file-organization.md \ No newline at end of file +../../standards/file-organization.md \ No newline at end of file diff --git a/.cursor/rules/quality-standards.mdc b/.cursor/rules/quality-standards.mdc index a7640b2aa0..b031026084 120000 --- a/.cursor/rules/quality-standards.mdc +++ b/.cursor/rules/quality-standards.mdc @@ -1 +1 @@ -../../.claude/rules/quality-standards.md \ No newline at end of file +../../standards/quality-standards.md \ No newline at end of file diff --git a/.cursor/rules/writing-style.mdc b/.cursor/rules/writing-style.mdc index 502fd404ed..f89c45f716 120000 --- a/.cursor/rules/writing-style.mdc +++ b/.cursor/rules/writing-style.mdc @@ -1 +1 @@ -../../.claude/rules/writing-style.md \ No newline at end of file +../../standards/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..8e3d7b574d 100644 --- a/.markdownlintignore +++ b/.markdownlintignore @@ -3,4 +3,6 @@ build .claude AGENTS.md CLAUDE.md +standards +workflows sources/_partials/* diff --git a/.vale.ini b/.vale.ini index b63185ce7a..0bac0f74a1 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 = + +[workflows/**/*.md] +BasedOnStyles = diff --git a/AGENTS.md b/AGENTS.md index d9a37c7786..ffd4a40407 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,124 +117,26 @@ Use `npm run start:dev` + nginx to serve all repos together locally. See `CONTRI --- -## Writing style - -### Language and tone - -- **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") - -### Headings - -- **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 - -Examples: - -| 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 | - -### 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 +## Standards + +Detailed writing and formatting standards are in `standards/`: + +- `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 + +Key rules at a glance: + +- 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 ## Review checklist diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53fc713230..59d1e8aa46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,45 +128,26 @@ 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 +- **`workflows/`** - Reusable processes for doc tasks (review, write, tutorial, API docs) +- **`AGENTS.md`** - Condensed summary + pointers (also `CLAUDE.md` via symlink) -- **`AGENTS.md`** - Primary vendor-agnostic rules file containing core documentation standards +### Agent-specific adapters -#### Cursor-specific rules - -- **`.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 - -To verify rule application, hover over attached rules in the Cursor chat window. +- **`.claude/skills/`** - Summary + pointer adapters for Claude Code (trigger metadata + process summary) +- **`.cursor/rules/`** - Thin pointers to `standards/` and `workflows/` 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/` and `workflows/` directly +- 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..b0d6982cc8 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 `workflows/doc-write/process.md`. See `workflows/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 `workflows/tutorial/process.md`. See `workflows/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 `workflows/api-doc/process.md`. See `workflows/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 `workflows/review-docs/process.md`. See `workflows/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 From e1123bb5b728de3d51da114fb3e1da0202b86ead Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 24 Mar 2026 14:06:20 +0100 Subject: [PATCH 3/6] chore: extract workflows and slim skills to summary + pointer adapters Move workflow processes and references from .claude/skills/ to workflows/ at repo root for agent parity. Rewrite all 4 SKILL.md files as summary + pointer adapters with AgentSkills spec compliance. Delete Cursor symlinks, rewrite .mdc files as thin pointers. Add check-frontmatter.sh script and workflows section to AGENTS.md. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/api-doc/SKILL.md | 137 +++--------------- .claude/skills/doc-write/SKILL.md | 119 +++------------ .claude/skills/review-docs/SKILL.md | 124 +++------------- .claude/skills/tutorial/SKILL.md | 129 +++-------------- .cursor/rules/api-documentation.mdc | 61 +------- .cursor/rules/content-formatting.mdc | 81 +---------- .cursor/rules/documentation-style.mdc | 57 +------- .cursor/rules/file-organization.mdc | 1 - .cursor/rules/quality-standards.mdc | 1 - .cursor/rules/writing-style.mdc | 1 - AGENTS.md | 9 ++ workflows/api-doc/process.md | 70 +++++++++ .../api-doc/references/openapi-patterns.md | 0 workflows/doc-write/process.md | 59 ++++++++ .../doc-write/references/doc-structures.md | 0 workflows/review-docs/process.md | 51 +++++++ .../review-docs/references/review-format.md | 0 .../review-docs/scripts/check-frontmatter.sh | 36 +++++ workflows/tutorial/process.md | 63 ++++++++ .../tutorial/references/tutorial-template.md | 0 20 files changed, 377 insertions(+), 622 deletions(-) delete mode 120000 .cursor/rules/file-organization.mdc delete mode 120000 .cursor/rules/quality-standards.mdc delete mode 120000 .cursor/rules/writing-style.mdc create mode 100644 workflows/api-doc/process.md rename {.claude/skills => workflows}/api-doc/references/openapi-patterns.md (100%) create mode 100644 workflows/doc-write/process.md rename {.claude/skills => workflows}/doc-write/references/doc-structures.md (100%) create mode 100644 workflows/review-docs/process.md rename {.claude/skills => workflows}/review-docs/references/review-format.md (100%) create mode 100755 workflows/review-docs/scripts/check-frontmatter.sh create mode 100644 workflows/tutorial/process.md rename {.claude/skills => workflows}/tutorial/references/tutorial-template.md (100%) diff --git a/.claude/skills/api-doc/SKILL.md b/.claude/skills/api-doc/SKILL.md index c37b4feddc..b98500c2f1 100644 --- a/.claude/skills/api-doc/SKILL.md +++ b/.claude/skills/api-doc/SKILL.md @@ -1,127 +1,28 @@ --- +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 -allowed-tools: Read, Write, Edit, Bash, Glob, Grep +allowed-tools: Read Write Edit Bash Glob Grep +metadata: + argument-hint: endpoint-name --- # API documentation -Create or update OpenAPI specifications and API documentation for Apify API endpoints. +## Process -## Instructions +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` -### Step 1: Identify the change type +**CRITICAL**: API docs are generated, not hand-written. Never edit files in `apify-api/docs/` directly. -- **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. +For detailed patterns and examples, see `workflows/api-doc/references/openapi-patterns.md`. +For edge cases and process notes, see `workflows/api-doc/process.md`. diff --git a/.claude/skills/doc-write/SKILL.md b/.claude/skills/doc-write/SKILL.md index ffbb265313..b64761fb9c 100644 --- a/.claude/skills/doc-write/SKILL.md +++ b/.claude/skills/doc-write/SKILL.md @@ -1,110 +1,25 @@ --- +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 -allowed-tools: Read, Write, Edit, Bash, Glob, Grep +allowed-tools: Read Write Edit Bash Glob Grep +metadata: + argument-hint: topic --- -# Documentation writer +# Documentation writing -Write or edit Apify documentation following the established style guide and best practices. +## Process -## Instructions +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 -### Step 1: Determine documentation type +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. -| 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. +For detailed structure templates, see `workflows/doc-write/references/doc-structures.md`. +For edge cases and process notes, see `workflows/doc-write/process.md`. diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md index ff4b114198..7129e50b62 100644 --- a/.claude/skills/review-docs/SKILL.md +++ b/.claude/skills/review-docs/SKILL.md @@ -1,114 +1,28 @@ --- +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 -allowed-tools: Read, Bash, Glob, Grep, Agent +allowed-tools: Read Bash Glob Grep Agent +metadata: + argument-hint: file-path --- # Documentation review -Review documentation for compliance with Apify style guide, quality standards, and best practices. +## Process -## Instructions +1. **Verify file version** - `git status` to confirm you have the latest +2. **Run deterministic checks** - 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) + - `workflows/review-docs/scripts/check-frontmatter.sh ""` (description char count) +3. **LLM review** - focus on what tools can't check: + - Content structure (clear intro, logical flow, next steps) + - Technical accuracy (code examples correct, API endpoints current) + - Completeness (prerequisites listed, edge cases covered) + - Terminology edge cases (check `standards/terminology.md` when unsure) + - Code example quality (complete, runnable, commented where needed) +4. **Format output** per `workflows/review-docs/references/review-format.md` -### Step 1: Check latest changes +Tools first, LLM second. Report tool failures as objective facts. Report LLM findings as judgment calls. -**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. +For detailed process notes and edge cases, see `workflows/review-docs/process.md`. diff --git a/.claude/skills/tutorial/SKILL.md b/.claude/skills/tutorial/SKILL.md index 8c86b6124b..6d85bad072 100644 --- a/.claude/skills/tutorial/SKILL.md +++ b/.claude/skills/tutorial/SKILL.md @@ -1,115 +1,30 @@ --- +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. -argument-hint: topic -allowed-tools: Read, Write, Edit, Bash, Glob, Grep +allowed-tools: Read Write Edit Bash Glob Grep +metadata: + argument-hint: topic --- -# Tutorial creator +# Tutorial creation -Create comprehensive, structured tutorials for Apify documentation following the 8-section template. +## Process -## Instructions +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 -### Step 1: Determine tutorial type +Each step should have a clear action verb, expected result, and verification. Code examples must be complete - no pseudocode. -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. +For the detailed 8-section template, see `workflows/tutorial/references/tutorial-template.md`. +For edge cases and process notes, see `workflows/tutorial/process.md`. diff --git a/.cursor/rules/api-documentation.mdc b/.cursor/rules/api-documentation.mdc index 2086f69a60..543e12326b 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 `workflows/api-doc/process.md`. +For OpenAPI patterns and examples, see `workflows/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..eb909843c7 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 `workflows/review-docs/process.md`. +When writing new pages, follow the process in `workflows/doc-write/process.md`. +When creating tutorials, follow the process in `workflows/tutorial/process.md`. +When writing API docs, follow the process in `workflows/api-doc/process.md`. diff --git a/.cursor/rules/file-organization.mdc b/.cursor/rules/file-organization.mdc deleted file mode 120000 index c939501367..0000000000 --- a/.cursor/rules/file-organization.mdc +++ /dev/null @@ -1 +0,0 @@ -../../standards/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 b031026084..0000000000 --- a/.cursor/rules/quality-standards.mdc +++ /dev/null @@ -1 +0,0 @@ -../../standards/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 f89c45f716..0000000000 --- a/.cursor/rules/writing-style.mdc +++ /dev/null @@ -1 +0,0 @@ -../../standards/writing-style.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index ffd4a40407..ac70a2ba4f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -138,6 +138,15 @@ Key rules at a glance: - See `standards/terminology.md` for Apify product name capitalization - Don't use em dashes (—) - use hyphen with spaces ( - ) instead +## Workflows + +Reusable documentation workflows are in `workflows/`: + +- `workflows/review-docs/` - Documentation review process and output format +- `workflows/doc-write/` - Writing and editing documentation pages +- `workflows/tutorial/` - Creating structured tutorials +- `workflows/api-doc/` - OpenAPI specification and API documentation + ## Review checklist When creating or reviewing documentation, verify: diff --git a/workflows/api-doc/process.md b/workflows/api-doc/process.md new file mode 100644 index 0000000000..5673e3873c --- /dev/null +++ b/workflows/api-doc/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/.claude/skills/api-doc/references/openapi-patterns.md b/workflows/api-doc/references/openapi-patterns.md similarity index 100% rename from .claude/skills/api-doc/references/openapi-patterns.md rename to workflows/api-doc/references/openapi-patterns.md diff --git a/workflows/doc-write/process.md b/workflows/doc-write/process.md new file mode 100644 index 0000000000..3c5a968723 --- /dev/null +++ b/workflows/doc-write/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/.claude/skills/doc-write/references/doc-structures.md b/workflows/doc-write/references/doc-structures.md similarity index 100% rename from .claude/skills/doc-write/references/doc-structures.md rename to workflows/doc-write/references/doc-structures.md diff --git a/workflows/review-docs/process.md b/workflows/review-docs/process.md new file mode 100644 index 0000000000..0e58563efe --- /dev/null +++ b/workflows/review-docs/process.md @@ -0,0 +1,51 @@ +# 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. + +- `npm run lint:md` (markdownlint: heading hierarchy, double spaces, list numbering) +- `vale "" --minAlertLevel=error` (prose style, dashes, code fences, admonitions) +- `workflows/review-docs/scripts/check-frontmatter.sh ""` (description char count) + +## Step 3: Manual review + +The deterministic tools handle mechanical checks. Focus on what requires understanding: + +- [ ] Content structure (clear intro, logical progression, next steps) +- [ ] Technical accuracy (code examples correct, API endpoints current) +- [ ] Completeness (prerequisites listed, edge cases addressed) +- [ ] Heading quality (sentence case nuances, gerund detection beyond -ing suffix) +- [ ] Terminology edge cases (check `standards/terminology.md` when unsure) +- [ ] 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 4: Format output + +Combine tool output and manual findings into structured review per `references/review-format.md`. + +- Tool findings are objective facts +- Manual findings are 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/workflows/review-docs/references/review-format.md similarity index 100% rename from .claude/skills/review-docs/references/review-format.md rename to workflows/review-docs/references/review-format.md diff --git a/workflows/review-docs/scripts/check-frontmatter.sh b/workflows/review-docs/scripts/check-frontmatter.sh new file mode 100755 index 0000000000..0d326e3cd0 --- /dev/null +++ b/workflows/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/workflows/tutorial/process.md b/workflows/tutorial/process.md new file mode 100644 index 0000000000..4b467d1c32 --- /dev/null +++ b/workflows/tutorial/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/workflows/tutorial/references/tutorial-template.md similarity index 100% rename from .claude/skills/tutorial/references/tutorial-template.md rename to workflows/tutorial/references/tutorial-template.md From 3e122baa2f8b54c5f27e63b79ca006ef6ad57b54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 24 Mar 2026 14:51:39 +0100 Subject: [PATCH 4/6] chore: peg review-docs to sonnet with hybrid subagent approach Eval showed Sonnet hybrid (summary + pointer adapter with delegated standards subagents) is the best tradeoff: ~80% cheaper than old Opus approach, 4% faster, and catches more issues. Deterministic tools run in main process (no sandbox issues), subagents handle standards review. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/review-docs/SKILL.md | 16 +++++++++++----- workflows/review-docs/process.md | 28 ++++++++++++++++++++-------- 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md index 7129e50b62..c844f9102d 100644 --- a/.claude/skills/review-docs/SKILL.md +++ b/.claude/skills/review-docs/SKILL.md @@ -2,6 +2,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. allowed-tools: Read Bash Glob Grep Agent +model: sonnet metadata: argument-hint: file-path --- @@ -11,18 +12,23 @@ metadata: ## Process 1. **Verify file version** - `git status` to confirm you have the latest -2. **Run deterministic checks** - these are objective, no judgment needed: +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) - `workflows/review-docs/scripts/check-frontmatter.sh ""` (description char count) -3. **LLM review** - focus on what tools can't check: +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) - - Terminology edge cases (check `standards/terminology.md` when unsure) - Code example quality (complete, runnable, commented where needed) -4. **Format output** per `workflows/review-docs/references/review-format.md` +5. **Format output** - merge subagent findings + deterministic results + content review per `workflows/review-docs/references/review-format.md` -Tools first, LLM second. Report tool failures as objective facts. Report LLM findings as judgment calls. +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 `workflows/review-docs/process.md`. diff --git a/workflows/review-docs/process.md b/workflows/review-docs/process.md index 0e58563efe..589f0242e1 100644 --- a/workflows/review-docs/process.md +++ b/workflows/review-docs/process.md @@ -9,31 +9,43 @@ Agent-agnostic workflow for reviewing Apify documentation. ## Step 2: Run deterministic checks -These are objective - no judgment needed. Report all failures. +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) - `workflows/review-docs/scripts/check-frontmatter.sh ""` (description char count) -## Step 3: Manual review +## Step 3: Delegated standards review -The deterministic tools handle mechanical checks. Focus on what requires understanding: +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) -- [ ] Heading quality (sentence case nuances, gerund detection beyond -ing suffix) -- [ ] Terminology edge cases (check `standards/terminology.md` when unsure) - [ ] 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 4: Format output +## Step 5: Format output -Combine tool output and manual findings into structured review per `references/review-format.md`. +Merge deterministic results + subagent findings + content review into structured output per `references/review-format.md`. - Tool findings are objective facts -- Manual findings are judgment calls +- Standards findings are rule-based judgment calls +- Content findings are subjective judgment calls - Prioritize by impact: critical → important → minor ## Edge cases From dd77714460441a9474c061bb36a5b8a322eb3be5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Wed, 25 Mar 2026 14:37:07 +0100 Subject: [PATCH 5/6] fix: restore argument-hint to top-level frontmatter, delete dead files Move argument-hint out of metadata: block back to top-level - Claude Code doesn't recognize metadata: nesting. Delete claude.json (not a real Claude Code config) and instructions.md (only referenced by claude.json). PR review feedback from marcel-rbro. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/README.md | 1 - .claude/claude.json | 6 ------ .claude/instructions.md | 28 ---------------------------- .claude/skills/api-doc/SKILL.md | 3 +-- .claude/skills/doc-write/SKILL.md | 3 +-- .claude/skills/review-docs/SKILL.md | 3 +-- .claude/skills/tutorial/SKILL.md | 3 +-- 7 files changed, 4 insertions(+), 43 deletions(-) delete mode 100644 .claude/claude.json delete mode 100644 .claude/instructions.md diff --git a/.claude/README.md b/.claude/README.md index 37360dc78e..2f3cea3b97 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -7,7 +7,6 @@ This directory contains Claude Code configuration for the Apify documentation re ```text .claude/ ├── README.md # This file - Quick start guide -├── instructions.md # Main instructions for Claude Code └── skills/ # Summary + pointer adapters for common tasks ├── doc-write/ # Documentation writing skill ├── api-doc/ # API documentation skill 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 b131837191..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 live in `standards/` at the repo root. Workflow processes live in `workflows/`. - -## 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/SKILL.md b/.claude/skills/api-doc/SKILL.md index b98500c2f1..93e9335317 100644 --- a/.claude/skills/api-doc/SKILL.md +++ b/.claude/skills/api-doc/SKILL.md @@ -2,8 +2,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. allowed-tools: Read Write Edit Bash Glob Grep -metadata: - argument-hint: endpoint-name +argument-hint: endpoint-name --- # API documentation diff --git a/.claude/skills/doc-write/SKILL.md b/.claude/skills/doc-write/SKILL.md index b64761fb9c..fff3e27fb4 100644 --- a/.claude/skills/doc-write/SKILL.md +++ b/.claude/skills/doc-write/SKILL.md @@ -2,8 +2,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. allowed-tools: Read Write Edit Bash Glob Grep -metadata: - argument-hint: topic +argument-hint: topic --- # Documentation writing diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md index c844f9102d..c5c5ff3bd8 100644 --- a/.claude/skills/review-docs/SKILL.md +++ b/.claude/skills/review-docs/SKILL.md @@ -3,8 +3,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. allowed-tools: Read Bash Glob Grep Agent model: sonnet -metadata: - argument-hint: file-path +argument-hint: file-path --- # Documentation review diff --git a/.claude/skills/tutorial/SKILL.md b/.claude/skills/tutorial/SKILL.md index 6d85bad072..60c4fe39dc 100644 --- a/.claude/skills/tutorial/SKILL.md +++ b/.claude/skills/tutorial/SKILL.md @@ -2,8 +2,7 @@ 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 -metadata: - argument-hint: topic +argument-hint: topic --- # Tutorial creation From e99697cc4815241573ed664207f066bb4224694a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 30 Mar 2026 19:12:44 +0200 Subject: [PATCH 6/6] chore: move skills to .agents/skills/ per AgentSkills spec, absorb workflows Skills now live in `.agents/skills/` (the AgentSkills open standard path), discoverable by Codex, Gemini CLI, OpenCode, Cursor, and other compatible agents. Claude Code discovers them via symlinks in `.claude/skills/`. Workflow content (process.md, references/, scripts/) absorbed into each skill's own `references/` and `scripts/` directories per the spec structure. The `workflows/` directory is deleted. Standards remain at repo root (shared). Co-Authored-By: Claude Opus 4.6 (1M context) --- {.claude => .agents}/skills/api-doc/SKILL.md | 4 +-- .../api-doc/references/openapi-patterns.md | 0 .../skills/api-doc/references}/process.md | 0 .../skills/doc-write/SKILL.md | 4 +-- .../doc-write/references/doc-structures.md | 0 .../skills/doc-write/references}/process.md | 0 .../skills/review-docs/SKILL.md | 6 ++--- .../skills/review-docs/references}/process.md | 2 +- .../review-docs/references/review-format.md | 0 .../review-docs/scripts/check-frontmatter.sh | 0 {.claude => .agents}/skills/tutorial/SKILL.md | 4 +-- .../skills/tutorial/references}/process.md | 0 .../tutorial/references/tutorial-template.md | 0 .claude/README.md | 25 ++++++++++++------- .claude/skills/api-doc | 1 + .claude/skills/doc-write | 1 + .claude/skills/review-docs | 1 + .claude/skills/tutorial | 1 + .cursor/rules/api-documentation.mdc | 4 +-- .cursor/rules/documentation-style.mdc | 8 +++--- .markdownlintignore | 2 +- .vale.ini | 2 +- AGENTS.md | 12 ++++----- CONTRIBUTING.md | 13 +++++++--- standards/quality-standards.md | 8 +++--- 25 files changed, 57 insertions(+), 41 deletions(-) rename {.claude => .agents}/skills/api-doc/SKILL.md (88%) rename {workflows => .agents/skills}/api-doc/references/openapi-patterns.md (100%) rename {workflows/api-doc => .agents/skills/api-doc/references}/process.md (100%) rename {.claude => .agents}/skills/doc-write/SKILL.md (89%) rename {workflows => .agents/skills}/doc-write/references/doc-structures.md (100%) rename {workflows/doc-write => .agents/skills/doc-write/references}/process.md (100%) rename {.claude => .agents}/skills/review-docs/SKILL.md (88%) rename {workflows/review-docs => .agents/skills/review-docs/references}/process.md (97%) rename {workflows => .agents/skills}/review-docs/references/review-format.md (100%) rename {workflows => .agents/skills}/review-docs/scripts/check-frontmatter.sh (100%) rename {.claude => .agents}/skills/tutorial/SKILL.md (89%) rename {workflows/tutorial => .agents/skills/tutorial/references}/process.md (100%) rename {workflows => .agents/skills}/tutorial/references/tutorial-template.md (100%) create mode 120000 .claude/skills/api-doc create mode 120000 .claude/skills/doc-write create mode 120000 .claude/skills/review-docs create mode 120000 .claude/skills/tutorial diff --git a/.claude/skills/api-doc/SKILL.md b/.agents/skills/api-doc/SKILL.md similarity index 88% rename from .claude/skills/api-doc/SKILL.md rename to .agents/skills/api-doc/SKILL.md index 93e9335317..3fce357a74 100644 --- a/.claude/skills/api-doc/SKILL.md +++ b/.agents/skills/api-doc/SKILL.md @@ -23,5 +23,5 @@ argument-hint: endpoint-name **CRITICAL**: API docs are generated, not hand-written. Never edit files in `apify-api/docs/` directly. -For detailed patterns and examples, see `workflows/api-doc/references/openapi-patterns.md`. -For edge cases and process notes, see `workflows/api-doc/process.md`. +For detailed patterns and examples, see `references/openapi-patterns.md`. +For edge cases and process notes, see `references/process.md`. diff --git a/workflows/api-doc/references/openapi-patterns.md b/.agents/skills/api-doc/references/openapi-patterns.md similarity index 100% rename from workflows/api-doc/references/openapi-patterns.md rename to .agents/skills/api-doc/references/openapi-patterns.md diff --git a/workflows/api-doc/process.md b/.agents/skills/api-doc/references/process.md similarity index 100% rename from workflows/api-doc/process.md rename to .agents/skills/api-doc/references/process.md diff --git a/.claude/skills/doc-write/SKILL.md b/.agents/skills/doc-write/SKILL.md similarity index 89% rename from .claude/skills/doc-write/SKILL.md rename to .agents/skills/doc-write/SKILL.md index fff3e27fb4..19242b2798 100644 --- a/.claude/skills/doc-write/SKILL.md +++ b/.agents/skills/doc-write/SKILL.md @@ -20,5 +20,5 @@ argument-hint: topic 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 `workflows/doc-write/references/doc-structures.md`. -For edge cases and process notes, see `workflows/doc-write/process.md`. +For detailed structure templates, see `references/doc-structures.md`. +For edge cases and process notes, see `references/process.md`. diff --git a/workflows/doc-write/references/doc-structures.md b/.agents/skills/doc-write/references/doc-structures.md similarity index 100% rename from workflows/doc-write/references/doc-structures.md rename to .agents/skills/doc-write/references/doc-structures.md diff --git a/workflows/doc-write/process.md b/.agents/skills/doc-write/references/process.md similarity index 100% rename from workflows/doc-write/process.md rename to .agents/skills/doc-write/references/process.md diff --git a/.claude/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md similarity index 88% rename from .claude/skills/review-docs/SKILL.md rename to .agents/skills/review-docs/SKILL.md index c5c5ff3bd8..4ac2c9a537 100644 --- a/.claude/skills/review-docs/SKILL.md +++ b/.agents/skills/review-docs/SKILL.md @@ -14,7 +14,7 @@ argument-hint: file-path 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) - - `workflows/review-docs/scripts/check-frontmatter.sh ""` (description char count) + - `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) @@ -26,8 +26,8 @@ argument-hint: file-path - 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 `workflows/review-docs/references/review-format.md` +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 `workflows/review-docs/process.md`. +For detailed process notes and edge cases, see `references/process.md`. diff --git a/workflows/review-docs/process.md b/.agents/skills/review-docs/references/process.md similarity index 97% rename from workflows/review-docs/process.md rename to .agents/skills/review-docs/references/process.md index 589f0242e1..62973d5928 100644 --- a/workflows/review-docs/process.md +++ b/.agents/skills/review-docs/references/process.md @@ -13,7 +13,7 @@ These are objective - no judgment needed. Report all failures. Run in the main p - `npm run lint:md` (markdownlint: heading hierarchy, double spaces, list numbering) - `vale "" --minAlertLevel=error` (prose style, dashes, code fences, admonitions) -- `workflows/review-docs/scripts/check-frontmatter.sh ""` (description char count) +- `scripts/check-frontmatter.sh ""` (description char count) ## Step 3: Delegated standards review diff --git a/workflows/review-docs/references/review-format.md b/.agents/skills/review-docs/references/review-format.md similarity index 100% rename from workflows/review-docs/references/review-format.md rename to .agents/skills/review-docs/references/review-format.md diff --git a/workflows/review-docs/scripts/check-frontmatter.sh b/.agents/skills/review-docs/scripts/check-frontmatter.sh similarity index 100% rename from workflows/review-docs/scripts/check-frontmatter.sh rename to .agents/skills/review-docs/scripts/check-frontmatter.sh diff --git a/.claude/skills/tutorial/SKILL.md b/.agents/skills/tutorial/SKILL.md similarity index 89% rename from .claude/skills/tutorial/SKILL.md rename to .agents/skills/tutorial/SKILL.md index 60c4fe39dc..75a9955112 100644 --- a/.claude/skills/tutorial/SKILL.md +++ b/.agents/skills/tutorial/SKILL.md @@ -25,5 +25,5 @@ argument-hint: topic 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 `workflows/tutorial/references/tutorial-template.md`. -For edge cases and process notes, see `workflows/tutorial/process.md`. +For the detailed 8-section template, see `references/tutorial-template.md`. +For edge cases and process notes, see `references/process.md`. diff --git a/workflows/tutorial/process.md b/.agents/skills/tutorial/references/process.md similarity index 100% rename from workflows/tutorial/process.md rename to .agents/skills/tutorial/references/process.md diff --git a/workflows/tutorial/references/tutorial-template.md b/.agents/skills/tutorial/references/tutorial-template.md similarity index 100% rename from workflows/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 2f3cea3b97..8baf8ba647 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -5,22 +5,29 @@ This directory contains Claude Code configuration for the Apify documentation re ## Structure ```text -.claude/ -├── README.md # This file - Quick start guide -└── skills/ # Summary + pointer adapters 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 ``` -Standards and workflows live at the repo root (agent-agnostic): +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 -workflows/ # Reusable processes for doc tasks ``` +Each skill contains its own `references/` and `scripts/` (formerly in `workflows/`). + ## How to use ### For Claude Code users 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/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/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/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/.cursor/rules/api-documentation.mdc b/.cursor/rules/api-documentation.mdc index 543e12326b..d2de63bdc0 100644 --- a/.cursor/rules/api-documentation.mdc +++ b/.cursor/rules/api-documentation.mdc @@ -3,5 +3,5 @@ description: API documentation standards for OpenAPI specifications globs: ["apify-api/**/*.yaml", "apify-api/**/*.js"] alwaysApply: true --- -For API documentation process and conventions, see `workflows/api-doc/process.md`. -For OpenAPI patterns and examples, see `workflows/api-doc/references/openapi-patterns.md`. +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/documentation-style.mdc b/.cursor/rules/documentation-style.mdc index eb909843c7..ef19b1d5a0 100644 --- a/.cursor/rules/documentation-style.mdc +++ b/.cursor/rules/documentation-style.mdc @@ -4,7 +4,7 @@ globs: ["sources/**/*.md", "sources/**/*.mdx"] alwaysApply: true --- When writing or editing documentation, follow the standards in `standards/`. -When reviewing documentation, follow the process in `workflows/review-docs/process.md`. -When writing new pages, follow the process in `workflows/doc-write/process.md`. -When creating tutorials, follow the process in `workflows/tutorial/process.md`. -When writing API docs, follow the process in `workflows/api-doc/process.md`. +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/.markdownlintignore b/.markdownlintignore index 8e3d7b574d..08e46a95bc 100644 --- a/.markdownlintignore +++ b/.markdownlintignore @@ -1,8 +1,8 @@ node_modules build .claude +.agents AGENTS.md CLAUDE.md standards -workflows sources/_partials/* diff --git a/.vale.ini b/.vale.ini index 0bac0f74a1..dd0d3863ab 100644 --- a/.vale.ini +++ b/.vale.ini @@ -40,5 +40,5 @@ BasedOnStyles = [standards/**/*.md] BasedOnStyles = -[workflows/**/*.md] +[.agents/**/*.md] BasedOnStyles = diff --git a/AGENTS.md b/AGENTS.md index ac70a2ba4f..bb5ef56083 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -138,14 +138,14 @@ Key rules at a glance: - See `standards/terminology.md` for Apify product name capitalization - Don't use em dashes (—) - use hyphen with spaces ( - ) instead -## Workflows +## Skills -Reusable documentation workflows are in `workflows/`: +Documentation skills live in `.agents/skills/` ([AgentSkills spec](https://agentskills.io)), each with its own `references/` and `scripts/`: -- `workflows/review-docs/` - Documentation review process and output format -- `workflows/doc-write/` - Writing and editing documentation pages -- `workflows/tutorial/` - Creating structured tutorials -- `workflows/api-doc/` - OpenAPI specification and API documentation +- `.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 59d1e8aa46..253d7dd984 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -135,17 +135,22 @@ This project uses an agent-agnostic approach: standards and workflows live at th ### Source of truth - **`standards/`** - Writing, formatting, terminology, and quality rules -- **`workflows/`** - Reusable processes for doc tasks (review, write, tutorial, API docs) +- **`.agents/skills/`** - Documentation skills with processes, references, and scripts (AgentSkills spec) - **`AGENTS.md`** - Condensed summary + pointers (also `CLAUDE.md` via symlink) +### Skills (AgentSkills standard) + +- **`.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 + ### Agent-specific adapters -- **`.claude/skills/`** - Summary + pointer adapters for Claude Code (trigger metadata + process summary) -- **`.cursor/rules/`** - Thin pointers to `standards/` and `workflows/` for Cursor +- **`.cursor/rules/`** - Thin pointers to `standards/` for Cursor ### Usage -- Any AI assistant can follow `AGENTS.md` and read `standards/` and `workflows/` directly +- 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 diff --git a/standards/quality-standards.md b/standards/quality-standards.md index b0d6982cc8..fc1896b99b 100644 --- a/standards/quality-standards.md +++ b/standards/quality-standards.md @@ -100,19 +100,19 @@ Before submitting documentation, verify: ### For documentation pages -Follow the writing process in `workflows/doc-write/process.md`. See `workflows/doc-write/references/doc-structures.md` for content type templates. +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 -Follow the tutorial process in `workflows/tutorial/process.md`. See `workflows/tutorial/references/tutorial-template.md` for the 8-section structure. +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 -Follow the API documentation process in `workflows/api-doc/process.md`. See `workflows/api-doc/references/openapi-patterns.md` for OpenAPI conventions. +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 -Follow the review process in `workflows/review-docs/process.md`. See `workflows/review-docs/references/review-format.md` for output format. +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