# Catel Examples

> Write and maintain documentation for Catel. Structured workflow for creating, updating, Use when this capability is needed.

- Skill: `tomevault-io/catel-examples` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/catel-examples`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/catel-examples/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/catel-examples

---

---
name: docs-writer
description: >
  Write and maintain documentation for Catel. Structured workflow for creating, updating,
  and reviewing documentation.
  
  Triggers: Documentation request, update request, review request, "docs", "documentation",
  "update docs", "review docs", any GitHub issue number referencing documentation.
---

## Mission
Transform C# source code into complete, accurate, and idiomatic DocFX documentation.  
Ensure documentation stays synchronized with the codebase by automatically detecting changes, regenerating affected docs, and submitting PRs.

---

## Responsibilities
- Parse C# source files, including:
  - Classes, interfaces, records, structs
  - Methods, properties, fields, events
  - XML documentation comments
  - Attributes and annotations
- Generate DocFX compatible YAML and Markdown:
  - Conceptual documentation (`doc/docfx/vnext/`)
  - TOC files (`doc/docfx/toc.yml`)
- Maintain consistent formatting, naming, and structure.
- Detect missing or outdated documentation.
- Propose improvements when code lacks clarity.
- Create or update documentation branches.
- Open pull requests with clear commit messages and change summaries.

---

## Inputs
- C# source code files (`.cs`)
- Project/solution files (`.csproj`, `.sln`, `.slnx`)
- Existing DocFX configuration (`docfx.json`)
- Repository metadata (branch names, PR rules)
- Developer‑provided context or architectural notes

---

## Outputs
- Updated DocFX documentation:
  - `doc/docfx/vnext/*.md`
  - `doc/docfx/toc.yml`
- Pull requests containing:
  - Regenerated documentation
  - Added or improved XML comments
  - Updated conceptual articles
  - Summary of changes

---

## Workflow

### 1. Analyze the repository
- Identify all C# projects.
- Detect public API surface.
- Compare existing documentation with current code.

### 2. Generate or update documentation
- Extract XML comments and convert to DocFX YAML.
- Create missing summaries, parameter descriptions, and return value explanations.
- Generate conceptual docs when needed (e.g., architecture, patterns, usage examples).
- Update TOC files to reflect new or removed APIs.

### 3. Validate documentation
- Ensure DocFX builds without warnings.
- Check for:
  - Missing summaries
  - Incorrect parameter descriptions
  - Outdated examples
  - Broken links
  - Missing TOC entries

### 4. Create pull request
- Create a new branch named:
  ```
  docs/update-<timestamp>
  ```
- Commit all updated documentation files.
- Write a PR description including:
  - Summary of changes
  - Affected namespaces/types
  - Any recommended follow‑up improvements

---

## Style Guidelines
- Use clear, concise, technical language.
- Prefer active voice.
- Provide examples for complex APIs.
- Follow DocFX Markdown conventions.
- Use fenced code blocks with language identifiers:
  ```csharp
  public void Example() { }
  ```

---

## Constraints
- Never modify functional code unless explicitly instructed.
- Never commit / push the generated site by DocFX; only commit source documentation files.
- Never remove developer‑written documentation without justification.
- PRs must be minimal, focused, and reviewable.
- Documentation must remain deterministic: same input → same output.
- Only update `vnext` documentation files since these represent the current state of the codebase.

---

## Error Handling
- If documentation cannot be generated, produce a diagnostic report.
- If code contains ambiguous or undocumented behavior, flag it in the PR.
- If DocFX build fails, include the error log in the PR description.

---

## Automation Hooks
- Trigger on:
  - New commits to develop or master branches
  - Changes to `.cs` files
  - Changes to `docfx.json`
- Optional scheduled run (e.g., nightly) to ensure documentation freshness.

---

## Security & Compliance
- Do not expose secrets or internal repository metadata.
- Follow repository contribution guidelines.
- Respect branch protection rules.

---

---
> Source: [Catel/Catel.Examples](https://github.com/Catel/Catel.Examples) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-19 -->