SKILL.md
Document Service
Generate comprehensive documentation for IntexuraOS services (apps, workers, and packages).
Usage
/document-service # List available services (discovery mode)
/document-service <service-name> # Document service interactively
Autonomous mode: Use Task tool with subagent_type: service-scribe for batch documentation without user interaction.
Team mode: Orchestrate parallel documentation agents for full monorepo coverage with cross-validation.
Core Mandates
- Code-First Analysis: Always analyze actual code before generating docs
- No Fabrication: Never invent version numbers, endpoints, env vars, resource limits, line counts, or method names — only document what exists in source code. See
workflows/autonomous.md Phase 3.5 for grounding rules
- Preserve User Insights: Never lose user-provided context from previous runs
- Incremental Updates: Website content updates are additive, not full regenerations
- Quality Assurance: Self-critique before writing files to disk — includes mandatory factual validation (Phase 4.5)
- Debt Tracking: Archive resolved items, never delete history
- Cross-Validation: After generation, validate docs against code and other service docs
- Typographic Consistency: Use em-dashes (
—) not ASCII double-dashes (--) for parenthetical statements
Output Files
Per Service (apps/workers) — 5 files
| File |
Purpose |
Audience |
features.md |
Value propositions, capabilities, use cases |
Users, marketing |
technical.md |
Architecture, APIs, patterns, gotchas |
Developers, AI agents |
tutorial.md |
Getting-started tutorial with exercises |
New developers |
technical-debt.md |
Known issues, debt items, future plans |
Maintainers |
agent.md |
Machine-readable interface (autonomous only) |
AI agents |
Per Package -- 3 files
| File |
Purpose |
Audience |
README.md |
Overview, API, dependencies, usage |
Developers |
technical-debt.md |
Known issues, debt items, future plans |
Maintainers |
agent.md |
Machine-readable interface |
AI agents |
Aggregation files
| File |
Purpose |
services/index.md |
Service catalog |
site-index.json |
Structured metadata |
overview.md |
Project narrative |
documentation-runs.md |
Run history log |
Cross-Validation reports
| File |
Purpose |
validation/http-contracts-*.md |
HTTP endpoint consistency |
validation/pubsub-contracts-*.md |
Pub/Sub topic/IAM consistency |
validation/ai-models-*.md |
AI model registry consistency |
validation/firestore-*.md |
Collection ownership consistency |
validation/package-deps-*.md |
Package dependency consistency |
validation/env-vars-*.md |
Environment variable consistency |
validation/v*-run-report.md |
Comprehensive run report |
Mode Selection
| Mode |
When to Use |
Invocation |
| Discovery |
List services, check doc status |
/document-service (no args) |
| Interactive |
Document one service with user input |
/document-service <service-name> |
| Autonomous |
Batch document one/few services |
Task tool -> service-scribe |
| Team |
Full monorepo docs + cross-validation |
Orchestrate parallel agents (see team.md) |
Invocation Detection
| Input Pattern |
Workflow |
/document-service |
[discovery.md](workflows/discovery.md) |
/document-service <service> |
[interactive.md](workflows/interactive.md) |
Task tool service-scribe subagent |
[autonomous.md](workflows/autonomous.md) |
| "Document all services" / team mode |
[team.md](workflows/team.md) |
| "Validate docs" / "cross-validate" |
[cross-validation.md](workflows/cross-validation.md) |
References
- Workflows: [
workflows/](workflows/)
- Templates: [
templates/](templates/)
- Reference: [
reference/](reference/)