From 8a40604ef60d65bc13d3aa3eea476947ebb0ad23 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Feb 2026 09:15:41 +0000 Subject: [PATCH 1/3] feat(docs): Add umbraco-docs documentation subagent skill Adds a Claude Code skill for writing and reviewing documentation following the official Umbraco documentation style guide and Vale linting rules. Includes reference documents for all 12 Vale rules and the complete writing style guide adapted for this multi-discipline repository (.NET, TypeScript, Lit, Umbraco CMS, EF Core, OpenAPI). https://claude.ai/code/session_01Bw3Qn5UpcJYaRXmnfgqjAM --- .claude/skills/umbraco-docs/SKILL.md | 233 ++++++++++++++ .claude/skills/umbraco-docs/STYLE-GUIDE.md | 349 +++++++++++++++++++++ .claude/skills/umbraco-docs/VALE-RULES.md | 325 +++++++++++++++++++ 3 files changed, 907 insertions(+) create mode 100644 .claude/skills/umbraco-docs/SKILL.md create mode 100644 .claude/skills/umbraco-docs/STYLE-GUIDE.md create mode 100644 .claude/skills/umbraco-docs/VALE-RULES.md diff --git a/.claude/skills/umbraco-docs/SKILL.md b/.claude/skills/umbraco-docs/SKILL.md new file mode 100644 index 00000000..7ae5cb49 --- /dev/null +++ b/.claude/skills/umbraco-docs/SKILL.md @@ -0,0 +1,233 @@ +--- +name: umbraco-docs +description: Writes and reviews documentation for Umbraco.AI following the official Umbraco documentation style guide and Vale linting rules. Covers .NET, TypeScript, Lit, Umbraco CMS, EF Core, and OpenAPI topics. Use when writing, reviewing, or improving documentation for any product in the repository. +argument-hint: [write|review|lint] +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +--- + +# Umbraco.AI Documentation Subagent + +Write and review documentation for Umbraco.AI products following the official Umbraco documentation style guide and Vale linting rules. + +## Command: $ARGUMENTS + +Execute the requested documentation task. + +## Available Commands + +### Writing + +- **write \**: Write new documentation on a topic (e.g., `write getting-started`, `write provider-api`) +- **write \**: Create or extend a specific documentation file + +### Reviewing + +- **review \**: Review an existing file against Umbraco style rules and Vale linting +- **review \**: Review all markdown files in a directory + +### Linting + +- **lint \**: Check a file against all 12 Vale rules and report violations +- **lint \**: Lint all markdown files in a directory + +## Implementation Guide + +### Step 1: Understand the Request + +Determine what the user needs: + +1. **Writing new docs**: Gather context from the codebase first. Read source files, interfaces, and existing docs to understand what needs documenting. +2. **Reviewing existing docs**: Read the target file(s) and check against every rule in [VALE-RULES.md](VALE-RULES.md) and [STYLE-GUIDE.md](STYLE-GUIDE.md). +3. **Linting**: Systematically check each of the 12 Vale rules and report all violations with line numbers. + +### Step 2: Gather Codebase Context + +Before writing documentation, always read the relevant source code: + +``` +# For .NET backend topics +Glob: src/**/I*.cs (interfaces) +Glob: src/**/*Service.cs (services) +Glob: src/**/*Controller.cs (API controllers) + +# For TypeScript/Lit frontend topics +Glob: Client/src/**/*.ts +Glob: Client/src/**/*.element.ts (Lit components) + +# For EF Core / database topics +Glob: src/**/*DbContext.cs +Glob: src/**/Migrations/*.cs + +# For OpenAPI topics +Glob: Client/src/api/**/*.ts (generated clients) +``` + +Read the product-specific `CLAUDE.md` for architectural context: + +``` +Read: /CLAUDE.md +``` + +### Step 3: Write or Review + +#### When Writing + +Follow the complete style guide in [STYLE-GUIDE.md](STYLE-GUIDE.md). Key rules: + +1. **Second person**: Address the reader as "you" +2. **Present tense, active voice**: "The profile loads" not "The profile was loaded" +3. **Sentences under 25 words** +4. **No editorializing**: Never use "simple", "easy", "just", "obviously", etc. +5. **Define acronyms on first use** (except common ones: API, CLI, CMS, CSS, HTML, JSON, URL, etc.) +6. **Correct Umbraco terms**: "backoffice" (one word), "Document Type" (capitalized), "Data Type" (capitalized) +7. **Correct tech names**: `.NET` (not "dot net"), `TypeScript` (not "typescript"), `JavaScript` (not "js") +8. **Inclusive language**: "primary" not "master", "allowlist" not "whitelist" +9. **Descriptive link text**: Never use "click here" or "read more" +10. **Code samples**: Use fenced code blocks with language identifiers + +#### When Reviewing + +Check the file against every rule. Report findings grouped by severity: + +**Errors** (must fix): +- Spacing: double spaces, missing space after punctuation +- Acronyms: undefined acronyms (3-5 uppercase letters) on first use + +**Warnings** (should fix): +- Heading punctuation at end of headings +- Sentence length over 25 words +- List items not starting with capital letter +- Editorializing language +- Repeated consecutive words +- Incorrect term usage (see Terms, UmbracoTerms, Names, Brands rules) +- Generic link text + +### Step 4: Validate Against Vale Rules + +Systematically check each of the 12 rules documented in [VALE-RULES.md](VALE-RULES.md): + +| # | Rule | Severity | What to Check | +|---|------|----------|---------------| +| 1 | HeadingsPunctuation | warning | No `.;:!?` at end of headings | +| 2 | Spacing | error | No double spaces; space after punctuation before capitals | +| 3 | SentenceLength | warning | Sentences under 25 words | +| 4 | ListStart | warning | List items start with capital letter | +| 5 | Editorializing | warning | No subjective/opinionated words | +| 6 | Repetition | warning | No repeated consecutive words | +| 7 | Acronyms | error | Define acronyms on first use (except ~130 common ones) | +| 8 | Terms | warning | Use inclusive and formal alternatives | +| 9 | UmbracoTerms | warning | Correct Umbraco product/concept casing | +| 10 | Names | warning | Correct tech name casing | +| 11 | Brands | warning | Correct brand name casing | +| 12 | LinkTextClarity | warning | No "here", "click here", "read more" link text | + +### Step 5: Multi-Discipline Awareness + +This repository spans multiple technology domains. Adapt documentation style to the audience: + +#### .NET / C# Documentation + +- Use `csharp` as the fenced code block language +- Reference namespaces, interfaces, and dependency injection patterns +- Follow the repository's `[Action][Entity]Async` naming convention in examples +- Mention `CancellationToken` parameters in async method signatures + +#### TypeScript / Lit Frontend Documentation + +- Use `typescript` or `ts` as the fenced code block language +- Reference Lit component lifecycle (`connectedCallback`, `render`, `updated`) +- Document custom element tag names and their properties +- Reference the Umbraco UI Library (UUI) components where relevant + +#### EF Core / Database Documentation + +- Document migration commands and naming prefixes (`UmbracoAI_`, `UmbracoAIPrompt_`, `UmbracoAIAgent_`) +- Mention both SQL Server and SQLite support +- Use `sql` for raw SQL examples, `csharp` for EF Core code + +#### OpenAPI / API Documentation + +- Document Management API endpoints with HTTP verbs and paths +- Reference the generated TypeScript clients from `@hey-api/openapi-ts` +- Include request/response examples in JSON + +#### Umbraco CMS Integration Documentation + +- Use correct Umbraco terminology (see UmbracoTerms rule) +- Reference Composers, Components, and the Umbraco DI pipeline +- Document backoffice UI integration points + +## Reference Documentation + +- **Vale rules (all 12)**: See [VALE-RULES.md](VALE-RULES.md) for complete rule definitions with patterns and examples +- **Writing style guide**: See [STYLE-GUIDE.md](STYLE-GUIDE.md) for Umbraco writing conventions, formatting, and structure + +## Output Format + +### For Writing Tasks + +Produce the markdown content directly. Include: + +- A single `#` title +- Hierarchical headings (`##`, `###`, etc.) +- Code samples with language identifiers +- Descriptive alt text for any images referenced + +### For Review Tasks + +Produce a structured report: + +``` +## Documentation Review: + +### Errors (must fix) +- **Line X**: [Rule] Description of issue + - Suggestion: ... + +### Warnings (should fix) +- **Line X**: [Rule] Description of issue + - Suggestion: ... + +### Summary +- X errors, Y warnings +- Overall assessment +``` + +### For Lint Tasks + +Produce a Vale-style report: + +``` + + Line X:Col Y error [UmbracoDocs.Spacing] Description + Line X:Col Y warning [UmbracoDocs.Editorializing] Description + ... + +N errors, M warnings +``` + +## Example Usage + +```bash +# Write new documentation +/umbraco-docs write getting-started-with-profiles + +# Review a file +/umbraco-docs review Umbraco.AI/README.md + +# Lint a directory +/umbraco-docs lint Umbraco.AI.OpenAI/ + +# Write provider-specific docs +/umbraco-docs write how-to-create-a-custom-provider +``` + +## Tips + +- Always read the source code before writing about it; do not guess at API shapes +- When documenting interfaces, read the implementation too for behavioral details +- Cross-reference existing documentation in the repo to maintain consistency +- For code samples, prefer examples that compile and work against the actual codebase +- Keep paragraphs short (3-4 sentences maximum) +- Use tables for reference material (configuration options, parameters, etc.) +- Use ordered lists only for sequential steps; unordered lists for everything else diff --git a/.claude/skills/umbraco-docs/STYLE-GUIDE.md b/.claude/skills/umbraco-docs/STYLE-GUIDE.md new file mode 100644 index 00000000..ab06c427 --- /dev/null +++ b/.claude/skills/umbraco-docs/STYLE-GUIDE.md @@ -0,0 +1,349 @@ +# Umbraco Documentation Style Guide + +This is a condensed reference of the official Umbraco documentation writing conventions, adapted for the Umbraco.AI repository. Based on the [Umbraco Style Guide](https://docs.umbraco.com/contributing/documentation/style-guide). + +## Voice and Tone + +### Second Person + +Address the reader directly using "you" and "your". Do not use "the user", "one", or "we". + +```markdown + +The user can configure a connection in the backoffice. +One should ensure the API key is valid. +We recommend using the default profile. + + +You can configure a connection in the backoffice. +Ensure the API key is valid. +Use the default profile for standard scenarios. +``` + +### Present Tense and Active Voice + +Write in present tense. Prefer active voice over passive. + +```markdown + +The connection was created and the profile was assigned. +The API key will be validated when the form is submitted. + + +The system creates the connection and assigns the profile. +The form validates the API key on submission. +``` + +### No Editorializing + +Never use subjective or opinionated language. See the full list in [VALE-RULES.md](VALE-RULES.md) Rule 5. + +The most commonly violated words in technical writing: + +| Do Not Use | Write Instead | +|------------|---------------| +| "simply add" | "add" | +| "just click" | "click" or "select" | +| "easy to configure" | "to configure" | +| "obviously" | (remove entirely) | +| "note that" | (restructure the sentence) | +| "basically" | (remove entirely) | + +## Sentence Structure + +### Length + +Keep sentences under 25 words. If a sentence exceeds this, split it. + +**Technique**: One idea per sentence. If you use "and" or "which" to connect clauses, consider splitting. + +```markdown + +When you configure a new AI connection in the Umbraco backoffice you need to select the provider type and enter the API key which you can obtain from the provider dashboard. + + +Configure a new AI connection in the Umbraco backoffice. Select the provider type and enter the API key from the provider dashboard. +``` + +### Ambiguous Pronouns + +Do not use "it" or "this" to refer to something in a previous sentence. Repeat the noun or restructure. + +```markdown + +Create a profile and assign it to a connection. It determines which model is used. + + +Create a profile and assign the profile to a connection. The profile determines which model is used. +``` + +## Formatting + +### Headings + +- Use a single `#` title per article +- Follow hierarchical order: `#` then `##` then `###` (never skip levels) +- No punctuation at the end of headings +- Use sentence case for headings (capitalize first word and proper nouns only) + +```markdown + +# Getting Started With AI Connections: +### Configuration (skipped ## level) + + +# Getting started with AI connections +## Configuration +### Provider settings +``` + +### Lists + +- **Ordered lists**: For sequential steps only. Start each item with an action verb. Maximum two actions per item. +- **Unordered lists**: For options, notes, criteria, and non-sequential items. +- All list items start with a capital letter (unless beginning with inline code or a URL). + +```markdown + +1. Navigate to the AI Settings section in the backoffice. +2. Select **Connections** from the sidebar. +3. Click **Create** and choose a provider. + + +- OpenAI supports chat and embedding capabilities +- Anthropic supports chat capability +- Amazon Bedrock supports chat capability +``` + +### Code Samples + +Use fenced code blocks with language identifiers. Keep samples focused and minimal. + +**Language identifiers for this repository**: + +| Language | Identifier | Use For | +|----------|-----------|---------| +| C# | `csharp` | .NET backend code | +| TypeScript | `typescript` | Frontend code, Lit components | +| JSON | `json` | Configuration, API responses | +| XML | `xml` | .csproj files, NuGet config | +| SQL | `sql` | Database queries | +| Bash | `bash` | CLI commands (Linux/Mac) | +| PowerShell | `powershell` | CLI commands (Windows) | +| HTML | `html` | Markup examples | + +**Code sample conventions**: + +```markdown + +``` +// This is a comprehensive example showing how you might +// configure the AI service with all available options +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddUmbracoAI(); +// ... many more lines +``` + + +```csharp +builder.Services.AddUmbracoAI(); +``` +``` + +### Inline Formatting + +- **Bold** (`**text**`): UI element names, button labels, field names +- *Italic* (`*text*`): Introducing new terms on first use +- `Code` (`` `text` ``): File names, paths, code references, CLI commands, parameter names + +```markdown +Click **Create** to open the connection form. Enter the *API key* in the +`ApiKey` field. Run `dotnet build` to verify the configuration. +``` + +### Links + +- Use descriptive link text (never "here", "click here", "read more") +- Use relative paths for internal links within the repository +- Use the article or section title as link text + +```markdown + +For more information, click [here](./configuration.md). + + +For more information, see [Connection configuration](./configuration.md). +``` + +### Images + +- Place images in an `images/` directory next to the referencing markdown file +- Use descriptive alt text +- Add captions where helpful +- File names: lowercase, hyphens instead of spaces + +```markdown +![The AI Connections list in the Umbraco backoffice](images/ai-connections-list.png) +``` + +## Terminology + +### Umbraco Terms + +Always use the correct casing and spelling: + +| Term | Notes | +|------|-------| +| Umbraco | Always capitalized | +| backoffice | One word, lowercase (unless starting a sentence) | +| Document Type | Two words, both capitalized | +| Data Type | Two words, both capitalized | +| Umbraco CMS | Product name | +| Umbraco Cloud | Product name | + +### Technology Names + +| Correct | Incorrect | +|---------|-----------| +| .NET | dot net, .net, dotnet (in prose) | +| TypeScript | typescript, Typescript, TS (in prose) | +| JavaScript | javascript, Javascript, JS (in prose) | +| CSS | css | +| HTML | html | +| SQL | sql (in prose) | +| EF Core | ef core, Entity Framework Core (after first use) | + +### Inclusive Language + +| Do Not Use | Use Instead | +|------------|-------------| +| master (branch) | primary (branch) | +| slave | secondary | +| blacklist | denylist | +| whitelist | allowlist | + +### Formal Alternatives + +| Do Not Use | Use Instead | +|------------|-------------| +| etc | and so on | +| e.g. | for example | +| i.e. | that is | +| aka | also known as | +| docs | documentation | + +## Acronyms + +Define all acronyms on first use in each article using one of these formats: + +```markdown + +The Large Language Model (LLM) processes the prompt. + + +LLM: Large Language Model +``` + +Common acronyms that do not need definition: API, CLI, CMS, CSS, HTML, HTTP, HTTPS, JSON, REST, SDK, SQL, UI, URL, UX, XML. See [VALE-RULES.md](VALE-RULES.md) Rule 7 for the full exceptions list. + +## File and Directory Structure + +- All file and directory names use lowercase +- Use hyphens instead of spaces +- Each directory should have a `README.md` as its landing page + +``` +getting-started/ +├── README.md +├── installation.md +├── configuration.md +└── images/ + ├── connection-form.png + └── profile-settings.png +``` + +## Umbraco.AI-Specific Conventions + +### Documenting APIs + +When documenting Management API endpoints: + +```markdown +### Get all connections + +`GET /umbraco/management/api/v1/ai/connection` + +Returns a list of all configured AI connections. + +**Response** (200): + +```json +{ + "items": [ + { + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "name": "My OpenAI Connection", + "providerAlias": "openai" + } + ] +} +``` +``` + +### Documenting .NET Services + +Follow the repository's naming conventions when showing service method signatures: + +```markdown +The `IAIProfileService` provides methods for managing AI profiles: + +```csharp +Task GetProfileAsync(Guid id, CancellationToken cancellationToken); +Task CreateProfileAsync(AIProfile profile, CancellationToken cancellationToken); +Task DeleteProfileAsync(Guid id, CancellationToken cancellationToken); +``` +``` + +### Documenting Lit Components + +When documenting frontend components, show the custom element usage: + +```markdown +The `umb-ai-connection-picker` element provides a dropdown for selecting AI connections: + +```html + + +``` +``` + +### Documenting Configuration + +Show both `appsettings.json` and C# configuration approaches: + +```markdown +## Configuration + +Add the AI settings to `appsettings.json`: + +```json +{ + "Umbraco": { + "AI": { + "DefaultCapability": "chat" + } + } +} +``` + +Or configure in code: + +```csharp +builder.Services.AddUmbracoAI(options => +{ + options.DefaultCapability = AICapability.Chat; +}); +``` +``` diff --git a/.claude/skills/umbraco-docs/VALE-RULES.md b/.claude/skills/umbraco-docs/VALE-RULES.md new file mode 100644 index 00000000..e9c87a6b --- /dev/null +++ b/.claude/skills/umbraco-docs/VALE-RULES.md @@ -0,0 +1,325 @@ +# Umbraco Documentation Vale Rules Reference + +These are the 12 Vale linting rules from the official [UmbracoDocs](https://github.com/umbraco/UmbracoDocs) repository. The rules live in `.github/styles/UmbracoDocs/` and are enforced on pull requests via the `errata-ai/vale-action@reviewdog` GitHub Action with `fail_on_error: true`. + +## Configuration + +```ini +# .vale.ini +StylesPath = .github/styles + +[*.md] +BasedOnStyles = UmbracoDocs +``` + +--- + +## Rule 1: HeadingsPunctuation (warning) + +Headings must not end with punctuation (`.`, `;`, `:`, `!`, `?`). + +**Pattern**: `(?:[.;:!]*)$` applied to heading scope + +**Examples**: + +```markdown + +## Getting Started. +## How does it work? +## Configuration: + + +## Getting Started +## How Does It Work +## Configuration +``` + +--- + +## Rule 2: Spacing (error) + +No double spaces after punctuation. No missing space after punctuation before a capital letter. + +**Patterns**: +- `[.?!,;:] {2,}` — double space after punctuation +- `[.?!,;:](?!\s)[A-Z]` — missing space after punctuation before uppercase + +**Examples**: + +```markdown + +This is a sentence. This has double space. +Run the command.Then check the output. + + +This is a sentence. This has single space. +Run the command. Then check the output. +``` + +--- + +## Rule 3: SentenceLength (warning) + +Sentences must contain fewer than 25 words. + +**Scope**: sentence +**Maximum**: 25 words (counted by `\b(\w+)\b` tokens) + +**Examples**: + +```markdown + +When you are configuring the AI provider connection settings in the backoffice you need to make sure that you have the correct API key entered in the field. + + +Configure the AI provider connection in the backoffice. Enter the correct API key in the connection settings. +``` + +--- + +## Rule 4: ListStart (warning) + +List items must start with a capital letter, unless they begin with inline code or a URL. + +**Pattern**: `^(?!\[|^)[a-z].+` applied to list scope + +**Examples**: + +```markdown + +- create a new connection +- navigate to the settings page + + +- Create a new connection +- Navigate to the settings page + + +- `dotnet build` compiles the solution +- [https://example.com](https://example.com) provides details +``` + +--- + +## Rule 5: Editorializing (warning) + +Avoid subjective or opinionated language. + +**Flagged words** (full list): + +`actually`, `aptly`, `are a number`, `basically`, `clearly`, `completely`, `easy`, `easily`, `essentially`, `everybody knows`, `everyone knows`, `exceedingly`, `excellent`, `extremely`, `fairly`, `fortunately`, `huge`, `interestingly`, `is a number`, `it is important to realize`, `it should be noted that`, `just`, `largely`, `mostly`, `notably`, `note that`, `obviously`, `of course`, `quite`, `relatively`, `remarkable`, `several`, `significantly`, `simple`, `simply`, `substantially`, `surprisingly`, `tiny`, `totally`, `tragically`, `unfortunately`, `untimely`, `various`, `vast`, `very`, `without a doubt` + +**Exceptions**: Technical uses like "Simple Mail Transfer Protocol" are excluded. + +**Examples**: + +```markdown + +This is a simple configuration process. +You can easily set up the connection. +Just add the API key and you're done. +Obviously, you need a valid key. + + +Configure the connection by adding the API key. +Add the API key to complete the setup. +A valid key is required. +``` + +--- + +## Rule 6: Repetition (warning) + +No repeated consecutive words. + +**Pattern**: Consecutive identical non-whitespace tokens + +**Examples**: + +```markdown + +The the connection is configured. +You can can use any provider. + + +The connection is configured. +You can use any provider. +``` + +--- + +## Rule 7: Acronyms (error) + +All acronyms (3-5 uppercase letters) must be defined on first use in each article, unless they appear in the exceptions list. + +**Definition formats accepted**: +- `ABC: Alpha Beta Charlie` (colon notation) +- `Alpha Beta Charlie (ABC)` (parenthetical) + +**Exceptions** (do not need definition — ~130 total, key ones listed): + +`API`, `ASP`, `CDN`, `CLI`, `CMS`, `CPU`, `CRUD`, `CSS`, `CSV`, `DNS`, `DOM`, `EOF`, `FTP`, `GIT`, `GPU`, `GUI`, `HTML`, `HTTP`, `HTTPS`, `IDE`, `IIS`, `IO`, `IP`, `JS`, `JSON`, `JWT`, `LINQ`, `MVC`, `NFS`, `NPM`, `NULL`, `ORM`, `OS`, `PDF`, `PHP`, `RAM`, `RBAC`, `REST`, `RSS`, `SDK`, `SMTP`, `SQL`, `SSD`, `SSH`, `SSL`, `SVG`, `TCP`, `TLS`, `TS`, `UDP`, `UI`, `URI`, `URL`, `USB`, `UTF`, `UX`, `VM`, `VPN`, `XML`, `XSS`, `YAML` + +**Examples**: + +```markdown + +The LLM processes the request. + + +The Large Language Model (LLM) processes the request. + +LLM: Large Language Model. The LLM processes the request. +``` + +--- + +## Rule 8: Terms (warning) + +Use inclusive and formal language alternatives. + +| Avoid | Use Instead | +|-------|-------------| +| `master` (branch/template/view) | `primary` (branch/template/view) | +| `slave` | `secondary` | +| `blacklist` / `blacklists` | `denylist` / `denylists` | +| `whitelist` / `whitelists` | `allowlist` / `allowlists` | +| `etc` | `and so on` | +| `e.g.` | `for example` | +| `i.e.` | `that is` | +| `aka` | `also known as` | +| `docs` | `documentation` | + +**Examples**: + +```markdown + +Add the domain to the whitelist, e.g. example.com, etc. + + +Add the domain to the allowlist, for example example.com, and so on. +``` + +--- + +## Rule 9: UmbracoTerms (warning) + +Enforces consistent capitalization of Umbraco-specific terms. + +| Incorrect | Correct | +|-----------|---------| +| `back-office`, `back office` | `backoffice` | +| `umbraco` (lowercase) | `Umbraco` | +| `document-type`, `document type` | `Document Type` | +| `doc-type`, `doc type` | `Document Type` | +| `data-type`, `data type` | `Data Type` | +| `heartcore` | `Heartcore` | +| `umbraco cloud` | `Umbraco Cloud` | +| `umbraco deploy` | `Umbraco Deploy` | +| `umbraco forms` | `Umbraco Forms` | +| `umbraco heartcore` | `Umbraco Heartcore` | +| `umbraco cms` | `Umbraco CMS` | +| `umbraco workflow` | `Umbraco Workflow` | +| `umbraco commerce` | `Umbraco Commerce` | +| `umbraco engage` | `Umbraco Engage` | +| `umbraco ui builder` | `Umbraco UI Builder` | + +**Examples**: + +```markdown + +Open the umbraco back-office and create a new document type. + + +Open the Umbraco backoffice and create a new Document Type. +``` + +--- + +## Rule 10: Names (warning) + +Enforces correct capitalization of common technology names. + +| Incorrect | Correct | +|-----------|---------| +| `css` | `CSS` | +| `html` | `HTML` | +| `url` | `URL` | +| `javascript`, `js` | `JavaScript` | +| `typescript`, `ts` | `TypeScript` | +| `.net`, `dot net` | `.NET` | +| `cms` | `CMS` | +| `angularjs` (various) | `AngularJS` | + +**Examples**: + +```markdown + +The frontend is built with typescript and uses css for styling. + + +The frontend is built with TypeScript and uses CSS for styling. +``` + +--- + +## Rule 11: Brands (warning) + +Enforces correct capitalization of brand names. Ignores matches inside markdown links and inline code. + +**Enforced brands**: `Azure`, `Azure DevOps`, `Chrome`, `Cloudflare`, `Firefox`, `GitBook`, `GitHub`, `macOS`, `Microsoft`, `NGINX`, `Safari`, `Slack`, `Twitter`, `Umbraco ID`, `Umbraco Support`, `Visual Studio Code` (including `vs code`), `YouTube` + +**Examples**: + +```markdown + +Deploy to azure using github actions. +Open the site in chrome or firefox. + + +Deploy to Azure using GitHub Actions. +Open the site in Chrome or Firefox. +``` + +--- + +## Rule 12: LinkTextClarity (warning) + +Link text must be descriptive. Generic text is flagged. + +**Flagged patterns**: +- `[here]` +- `[click here]` +- `[read more]` +- `[more info]` + +**Examples**: + +```markdown + +For details, [click here](https://example.com). +Learn more [here](https://example.com). + + +For details, see the [Connection Configuration guide](https://example.com). +Learn more in the [API reference](https://example.com). +``` + +--- + +## Quick Reference Table + +| # | Rule | Level | Key Check | +|---|------|-------|-----------| +| 1 | HeadingsPunctuation | warning | No `.;:!?` at end of headings | +| 2 | Spacing | **error** | Single space after punctuation | +| 3 | SentenceLength | warning | < 25 words per sentence | +| 4 | ListStart | warning | Capital letter start (unless code/URL) | +| 5 | Editorializing | warning | No subjective language | +| 6 | Repetition | warning | No consecutive duplicate words | +| 7 | Acronyms | **error** | Define on first use (except common) | +| 8 | Terms | warning | Inclusive/formal alternatives | +| 9 | UmbracoTerms | warning | Correct Umbraco term casing | +| 10 | Names | warning | Correct tech name casing | +| 11 | Brands | warning | Correct brand name casing | +| 12 | LinkTextClarity | warning | Descriptive link text | From f4d6053e7a36e2b7b66df847be5bae0799e411fa Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Feb 2026 09:22:48 +0000 Subject: [PATCH 2/3] refactor(docs): Focus documentation subagent on public APIs and concise content Reorient the umbraco-docs skill toward user-facing documentation: - Add documentation philosophy: public APIs only, concise over comprehensive, progressive disclosure, one task per page - Scope codebase research to public surface area (extension methods, public interfaces, controllers) and exclude internals - Add depth calibration table and "what to omit" guidance - Replace internal-facing examples with user-facing patterns (installation, configuration, backoffice navigation) https://claude.ai/code/session_01Bw3Qn5UpcJYaRXmnfgqjAM --- .claude/skills/umbraco-docs/SKILL.md | 109 ++++++++++++------- .claude/skills/umbraco-docs/STYLE-GUIDE.md | 117 +++++++++++---------- 2 files changed, 131 insertions(+), 95 deletions(-) diff --git a/.claude/skills/umbraco-docs/SKILL.md b/.claude/skills/umbraco-docs/SKILL.md index 7ae5cb49..53acadc5 100644 --- a/.claude/skills/umbraco-docs/SKILL.md +++ b/.claude/skills/umbraco-docs/SKILL.md @@ -1,13 +1,25 @@ --- name: umbraco-docs -description: Writes and reviews documentation for Umbraco.AI following the official Umbraco documentation style guide and Vale linting rules. Covers .NET, TypeScript, Lit, Umbraco CMS, EF Core, and OpenAPI topics. Use when writing, reviewing, or improving documentation for any product in the repository. +description: Writes and reviews user-facing documentation for Umbraco.AI following the official Umbraco documentation style guide and Vale linting rules. Focuses on public APIs, extension points, and getting-started guides. Use when writing, reviewing, or improving documentation for any product in the repository. argument-hint: [write|review|lint] allowed-tools: Read, Write, Edit, Glob, Grep, Bash --- # Umbraco.AI Documentation Subagent -Write and review documentation for Umbraco.AI products following the official Umbraco documentation style guide and Vale linting rules. +Write and review user-facing documentation for Umbraco.AI products following the official Umbraco documentation style guide and Vale linting rules. + +## Documentation Philosophy + +**Audience**: Umbraco developers integrating AI into their sites. They know Umbraco CMS but may be new to AI concepts and this package ecosystem. + +**Core principles**: + +1. **Public APIs only** — Document what users consume: NuGet/npm packages, public interfaces, extension methods, configuration options, backoffice UI, and Management API endpoints. Never document internal services, repositories, or implementation details. +2. **Concise over comprehensive** — Show how to use something with a minimal working example. Do not enumerate every overload, every property, or every edge case. A reader should be able to scan a page and start working within minutes. +3. **Progressive disclosure** — Start with the common case. Mention advanced options exist and link to them, but do not front-load complexity. A getting-started guide should not read like a reference manual. +4. **One task per page** — Each article answers one question: "How do I configure a connection?", "How do I create a custom provider?". If an article tries to answer multiple questions, split it. +5. **Code speaks louder than prose** — A 5-line code sample with a one-sentence explanation beats three paragraphs of description. When in doubt, show the code. ## Command: $ARGUMENTS @@ -42,26 +54,37 @@ Determine what the user needs: ### Step 2: Gather Codebase Context -Before writing documentation, always read the relevant source code: +Before writing documentation, read the **public surface area** of the relevant code. Focus on what users install, configure, and call — not internal implementation. + +**What to read (public API)**: ``` -# For .NET backend topics -Glob: src/**/I*.cs (interfaces) -Glob: src/**/*Service.cs (services) -Glob: src/**/*Controller.cs (API controllers) +# Public extension methods (the main entry point for users) +Glob: src/**/*Extensions.cs +Glob: src/**/*BuilderExtensions.cs + +# Public interfaces users interact with +Glob: src/**/I*Service.cs (only public ones in .Core projects) +Glob: src/**/I*Provider.cs -# For TypeScript/Lit frontend topics -Glob: Client/src/**/*.ts -Glob: Client/src/**/*.element.ts (Lit components) +# Configuration / options classes +Glob: src/**/*Options.cs +Glob: src/**/*Settings.cs -# For EF Core / database topics -Glob: src/**/*DbContext.cs -Glob: src/**/Migrations/*.cs +# Management API controllers (REST endpoints users call) +Glob: src/**/*Controller.cs -# For OpenAPI topics -Glob: Client/src/api/**/*.ts (generated clients) +# Frontend elements users can place in the backoffice +Glob: Client/src/**/*.element.ts ``` +**What NOT to read or document**: + +- Internal repositories (`I*Repository.cs`) — implementation detail +- DbContext / migrations — users do not interact with these +- Internal services that are not in the DI container publicly +- Private/internal helper classes + Read the product-specific `CLAUDE.md` for architectural context: ``` @@ -123,39 +146,32 @@ Systematically check each of the 12 rules documented in [VALE-RULES.md](VALE-RUL ### Step 5: Multi-Discipline Awareness -This repository spans multiple technology domains. Adapt documentation style to the audience: +This repository spans multiple technology domains. Always write from the **user's perspective** — what they install, configure, and call. #### .NET / C# Documentation - Use `csharp` as the fenced code block language -- Reference namespaces, interfaces, and dependency injection patterns -- Follow the repository's `[Action][Entity]Async` naming convention in examples -- Mention `CancellationToken` parameters in async method signatures +- Focus on: NuGet package installation, `AddUmbraco*()` extension methods, configuration in `appsettings.json`, and public service interfaces +- Show the minimal code to achieve a task — do not show every overload +- Do not document internal DI registrations, repositories, or persistence details #### TypeScript / Lit Frontend Documentation -- Use `typescript` or `ts` as the fenced code block language -- Reference Lit component lifecycle (`connectedCallback`, `render`, `updated`) -- Document custom element tag names and their properties -- Reference the Umbraco UI Library (UUI) components where relevant - -#### EF Core / Database Documentation +- Use `typescript` as the fenced code block language +- Focus on: npm package installation, custom element tag names, and key properties/events +- Do not document internal component architecture or Lit lifecycle internals -- Document migration commands and naming prefixes (`UmbracoAI_`, `UmbracoAIPrompt_`, `UmbracoAIAgent_`) -- Mention both SQL Server and SQLite support -- Use `sql` for raw SQL examples, `csharp` for EF Core code +#### Management API Documentation -#### OpenAPI / API Documentation - -- Document Management API endpoints with HTTP verbs and paths -- Reference the generated TypeScript clients from `@hey-api/openapi-ts` -- Include request/response examples in JSON +- Document endpoints with HTTP verb, path, and a single request/response example +- Reference the generated TypeScript client methods when relevant +- Do not document every query parameter variation — show the common case #### Umbraco CMS Integration Documentation - Use correct Umbraco terminology (see UmbracoTerms rule) -- Reference Composers, Components, and the Umbraco DI pipeline -- Document backoffice UI integration points +- Focus on: Composer setup, backoffice navigation, and configuration sections +- Do not explain Umbraco internals the reader already knows (they are Umbraco developers) ## Reference Documentation @@ -222,12 +238,27 @@ N errors, M warnings /umbraco-docs write how-to-create-a-custom-provider ``` +## Depth Calibration + +Use this guide to decide how much detail to include: + +| Content Type | Right Depth | Too Deep | +|---|---|---| +| Getting started | Install, configure, first working example | Every configuration option explained | +| How-to guide | Steps to complete one task, with code | Multiple approaches compared in detail | +| API reference | Method signature, one-line description, example | Full parameter docs for every overload | +| Configuration | Common options with defaults, example JSON | Every option with edge cases | +| Concepts | What it is, why it matters, how it connects | Internal architecture and design decisions | + +**Rule of thumb**: If a section makes the reader scroll more than twice without learning something actionable, it is too long. Move details to a linked reference page or remove them. + ## Tips - Always read the source code before writing about it; do not guess at API shapes -- When documenting interfaces, read the implementation too for behavioral details +- Focus on public interfaces — if a class is `internal`, it does not belong in user documentation - Cross-reference existing documentation in the repo to maintain consistency -- For code samples, prefer examples that compile and work against the actual codebase -- Keep paragraphs short (3-4 sentences maximum) -- Use tables for reference material (configuration options, parameters, etc.) +- For code samples, prefer the shortest example that compiles and demonstrates the feature +- Keep paragraphs to 2-3 sentences maximum +- Use tables for reference material (configuration options, parameters) - Use ordered lists only for sequential steps; unordered lists for everything else +- When a topic has a simple path and an advanced path, document the simple path inline and link to the advanced path diff --git a/.claude/skills/umbraco-docs/STYLE-GUIDE.md b/.claude/skills/umbraco-docs/STYLE-GUIDE.md index ab06c427..d2a5bfb1 100644 --- a/.claude/skills/umbraco-docs/STYLE-GUIDE.md +++ b/.claude/skills/umbraco-docs/STYLE-GUIDE.md @@ -2,6 +2,30 @@ This is a condensed reference of the official Umbraco documentation writing conventions, adapted for the Umbraco.AI repository. Based on the [Umbraco Style Guide](https://docs.umbraco.com/contributing/documentation/style-guide). +## Audience and Depth + +**Who reads this documentation**: Umbraco developers adding AI capabilities to their CMS sites. They are comfortable with Umbraco, .NET, and web development, but may be new to AI services and this package. + +**What to document**: Public APIs, NuGet/npm packages, configuration, backoffice UI, extension points, and Management API endpoints. + +**What NOT to document**: Internal services, repositories, database schemas, EF Core migrations, or private implementation details. These are not part of the user contract and change without notice. + +**How deep to go**: Show the reader how to achieve a task with a minimal working example. Mention that advanced options exist and link to reference material, but do not front-load complexity. A reader scanning the page should find a working code sample within the first scroll. + +```markdown + +The `AIProfileService` uses the `IAIProfileRepository` internally to persist +profiles to the database via EF Core. The repository calls `DbSet` +on the `AIDbContext`, which supports both SQL Server and SQLite... + + +To retrieve a profile by ID, inject `IAIProfileService`: + +```csharp +var profile = await profileService.GetProfileAsync(profileId, cancellationToken); +``` +``` + ## Voice and Tone ### Second Person @@ -264,69 +288,29 @@ getting-started/ ## Umbraco.AI-Specific Conventions -### Documenting APIs +### Depth Guidelines by Content Type -When documenting Management API endpoints: +**Installation / Getting Started**: Show the NuGet install command and the one-line DI registration. Link to configuration for next steps. ```markdown -### Get all connections +Install the package: -`GET /umbraco/management/api/v1/ai/connection` - -Returns a list of all configured AI connections. - -**Response** (200): - -```json -{ - "items": [ - { - "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", - "name": "My OpenAI Connection", - "providerAlias": "openai" - } - ] -} -``` +```bash +dotnet add package Umbraco.AI.OpenAI ``` -### Documenting .NET Services - -Follow the repository's naming conventions when showing service method signatures: - -```markdown -The `IAIProfileService` provides methods for managing AI profiles: +Register the provider in `Program.cs`: ```csharp -Task GetProfileAsync(Guid id, CancellationToken cancellationToken); -Task CreateProfileAsync(AIProfile profile, CancellationToken cancellationToken); -Task DeleteProfileAsync(Guid id, CancellationToken cancellationToken); +builder.Services.AddUmbracoAI() + .AddOpenAI(); ``` ``` -### Documenting Lit Components - -When documenting frontend components, show the custom element usage: +**Configuration**: Lead with `appsettings.json` (most common path). Mention code-based configuration exists and link to it, but do not show both inline unless the article is specifically about configuration. ```markdown -The `umb-ai-connection-picker` element provides a dropdown for selecting AI connections: - -```html - - -``` -``` - -### Documenting Configuration - -Show both `appsettings.json` and C# configuration approaches: - -```markdown -## Configuration - -Add the AI settings to `appsettings.json`: +Add the connection settings to `appsettings.json`: ```json { @@ -338,12 +322,33 @@ Add the AI settings to `appsettings.json`: } ``` -Or configure in code: +You can also [configure options in code](./advanced-configuration.md). +``` -```csharp -builder.Services.AddUmbracoAI(options => -{ - options.DefaultCapability = AICapability.Chat; -}); +**Management API endpoints**: Show the HTTP verb, path, and one example. Do not document every query parameter — link to the OpenAPI spec for full details. + +```markdown +### Get all connections + +`GET /umbraco/management/api/v1/ai/connection` + +Returns all configured AI connections. ``` + +**Backoffice UI**: Describe the navigation path and what the user sees. Use screenshots sparingly — one per major workflow step is enough. + +```markdown +1. Open the **Settings** section in the Umbraco backoffice. +2. Select **AI Connections** from the sidebar. +3. Click **Create** to add a new connection. ``` + +### What to Omit + +Do not document: + +- Internal service implementations or repository patterns +- Database schema, migrations, or EF Core details +- Private or internal classes +- DI registration internals beyond the public extension methods +- Build tooling or CI pipeline configuration (this is contributor documentation, not user documentation) From f356a20d46062d4803a1e66cdcb516a0963309c4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Feb 2026 10:26:53 +0000 Subject: [PATCH 3/3] refactor(docs): Rename skill to docs-writer https://claude.ai/code/session_01Bw3Qn5UpcJYaRXmnfgqjAM --- .claude/skills/{umbraco-docs => docs-writer}/SKILL.md | 10 +++++----- .../{umbraco-docs => docs-writer}/STYLE-GUIDE.md | 0 .../skills/{umbraco-docs => docs-writer}/VALE-RULES.md | 0 3 files changed, 5 insertions(+), 5 deletions(-) rename .claude/skills/{umbraco-docs => docs-writer}/SKILL.md (98%) rename .claude/skills/{umbraco-docs => docs-writer}/STYLE-GUIDE.md (100%) rename .claude/skills/{umbraco-docs => docs-writer}/VALE-RULES.md (100%) diff --git a/.claude/skills/umbraco-docs/SKILL.md b/.claude/skills/docs-writer/SKILL.md similarity index 98% rename from .claude/skills/umbraco-docs/SKILL.md rename to .claude/skills/docs-writer/SKILL.md index 53acadc5..29b37ab4 100644 --- a/.claude/skills/umbraco-docs/SKILL.md +++ b/.claude/skills/docs-writer/SKILL.md @@ -1,5 +1,5 @@ --- -name: umbraco-docs +name: docs-writer description: Writes and reviews user-facing documentation for Umbraco.AI following the official Umbraco documentation style guide and Vale linting rules. Focuses on public APIs, extension points, and getting-started guides. Use when writing, reviewing, or improving documentation for any product in the repository. argument-hint: [write|review|lint] allowed-tools: Read, Write, Edit, Glob, Grep, Bash @@ -226,16 +226,16 @@ N errors, M warnings ```bash # Write new documentation -/umbraco-docs write getting-started-with-profiles +/docs-writer write getting-started-with-profiles # Review a file -/umbraco-docs review Umbraco.AI/README.md +/docs-writer review Umbraco.AI/README.md # Lint a directory -/umbraco-docs lint Umbraco.AI.OpenAI/ +/docs-writer lint Umbraco.AI.OpenAI/ # Write provider-specific docs -/umbraco-docs write how-to-create-a-custom-provider +/docs-writer write how-to-create-a-custom-provider ``` ## Depth Calibration diff --git a/.claude/skills/umbraco-docs/STYLE-GUIDE.md b/.claude/skills/docs-writer/STYLE-GUIDE.md similarity index 100% rename from .claude/skills/umbraco-docs/STYLE-GUIDE.md rename to .claude/skills/docs-writer/STYLE-GUIDE.md diff --git a/.claude/skills/umbraco-docs/VALE-RULES.md b/.claude/skills/docs-writer/VALE-RULES.md similarity index 100% rename from .claude/skills/umbraco-docs/VALE-RULES.md rename to .claude/skills/docs-writer/VALE-RULES.md