Back to Details

oss-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OSS Documentation Skill

OSS文档技能

Scaffold and audit documentation for open source projects.
为开源项目搭建和审核文档。

Overview

概述

This skill helps prepare repositories for open source release by:
  1. Auditing existing documentation completeness
  2. Scaffolding missing standard files
  3. Generating content tailored to project type
该技能通过以下方式帮助仓库为开源发布做好准备：
  1. 审核现有文档的完整性
  2. 搭建缺失的标准文件
  3. 生成适配项目类型的内容

Commands

命令

CommandAction
audit
Check which OSS docs exist/missing
scaffold
Create all missing standard files
scaffold [file]
Create specific file
update
Refresh existing docs with latest patterns
validate
Check docs follow best practices
命令操作
audit
检查OSS文档的存在/缺失情况
scaffold
创建所有缺失的标准文件
scaffold [file]
创建指定文件
update
用最新范式刷新现有文档
validate
检查文档是否遵循最佳实践

Phase 0: Project Detection

阶段0：项目检测

bash
undefined
bash
undefined

Determine project type and language

Determine project type and language

PROJECT_NAME=$(basename $(pwd)) LANGUAGES=()
[[ -f go.mod ]] && LANGUAGES+=("go") [[ -f pyproject.toml ]] || [[ -f setup.py ]] && LANGUAGES+=("python") [[ -f package.json ]] && LANGUAGES+=("javascript") [[ -f Cargo.toml ]] && LANGUAGES+=("rust")
PROJECT_NAME=$(basename $(pwd)) LANGUAGES=()
[[ -f go.mod ]] && LANGUAGES+=("go") [[ -f pyproject.toml ]] || [[ -f setup.py ]] && LANGUAGES+=("python") [[ -f package.json ]] && LANGUAGES+=("javascript") [[ -f Cargo.toml ]] && LANGUAGES+=("rust")

Detect project category

Detect project category

if [[ -f Dockerfile ]] && [[ -d cmd ]]; then PROJECT_TYPE="cli" elif [[ -d config/crd ]]; then PROJECT_TYPE="operator" elif [[ -f Chart.yaml ]]; then PROJECT_TYPE="helm" else PROJECT_TYPE="library" fi

---
if [[ -f Dockerfile ]] && [[ -d cmd ]]; then PROJECT_TYPE="cli" elif [[ -d config/crd ]]; then PROJECT_TYPE="operator" elif [[ -f Chart.yaml ]]; then PROJECT_TYPE="helm" else PROJECT_TYPE="library" fi

---

Subcommand: audit

子命令：audit

Required Files (Tier 1 - Core)

必备文件（层级1 - 核心）

FilePurpose
LICENSE
Legal terms
README.md
Project overview
CONTRIBUTING.md
How to contribute
CODE_OF_CONDUCT.md
Community standards
文件用途
LICENSE
法律条款
README.md
项目概述
CONTRIBUTING.md
贡献指南
CODE_OF_CONDUCT.md
社区准则

Recommended Files (Tier 2 - Standard)

推荐文件（层级2 - 标准）

FilePurpose
SECURITY.md
Vulnerability reporting
CHANGELOG.md
Version history
AGENTS.md
AI assistant context
.github/ISSUE_TEMPLATE/
Issue templates
.github/PULL_REQUEST_TEMPLATE.md
PR template
文件用途
SECURITY.md
漏洞上报
CHANGELOG.md
版本历史
AGENTS.md
AI助手上下文
.github/ISSUE_TEMPLATE/
问题模板
.github/PULL_REQUEST_TEMPLATE.md
PR模板

Optional Files (Tier 3 - Enhanced)

可选文件（层级3 - 增强）

FileWhen Needed
docs/QUICKSTART.md
Complex setup
docs/ARCHITECTURE.md
Non-trivial codebase
docs/CLI_REFERENCE.md
CLI tools
docs/CONFIG.md
Configurable software
examples/
Complex workflows
文件适用场景
docs/QUICKSTART.md
复杂安装配置
docs/ARCHITECTURE.md
非平凡代码库
docs/CLI_REFERENCE.md
CLI工具
docs/CONFIG.md
可配置软件
examples/
复杂工作流

Subcommand: scaffold

子命令：scaffold

Template Selection

模板选择

Project TypeFocus
cli
Installation, commands, examples
operator
K8s CRDs, RBAC, deployment
service
API, configuration, deployment
library
API reference, examples
helm
Values, dependencies, upgrading
项目类型重点内容
cli
安装、命令、示例
operator
K8s CRDs、RBAC、部署
service
API、配置、部署
library
API参考、示例
helm
配置值、依赖、升级

Documentation Organization

文档组织结构

project/
├── README.md              # Overview + quick start
├── AGENTS.md              # AI assistant context
├── CONTRIBUTING.md        # Contributor guide
├── CHANGELOG.md           # Keep a Changelog format
├── docs/
│   ├── QUICKSTART.md      # Detailed getting started
│   ├── CLI_REFERENCE.md   # Complete command reference
│   ├── ARCHITECTURE.md    # System design
│   └── CONFIG.md          # Configuration options
└── examples/
    └── README.md          # Examples index
project/
├── README.md              # Overview + quick start
├── AGENTS.md              # AI assistant context
├── CONTRIBUTING.md        # Contributor guide
├── CHANGELOG.md           # Keep a Changelog format
├── docs/
│   ├── QUICKSTART.md      # Detailed getting started
│   ├── CLI_REFERENCE.md   # Complete command reference
│   ├── ARCHITECTURE.md    # System design
│   └── CONFIG.md          # Configuration options
└── examples/
    └── README.md          # Examples index

AGENTS.md Pattern

AGENTS.md 范式

markdown
undefined
markdown
undefined

Agent Instructions

Agent Instructions

This project uses <tool> for <purpose>. Run 
<onboard-cmd>
to get started.
This project uses <tool> for <purpose>. Run 
<onboard-cmd>
to get started.

Quick Reference

Quick Reference

bash
<cmd1>              # Do thing 1
<cmd2>              # Do thing 2
bash
<cmd1>              # Do thing 1
<cmd2>              # Do thing 2

Landing the Plane (Session Completion)

Landing the Plane (Session Completion)

MANDATORY WORKFLOW:
  1. Run quality gates - Tests, linters, builds
  2. Commit changes - Meaningful commit message
  3. PUSH TO REMOTE - This is MANDATORY
  4. Verify - All changes committed AND pushed

---
MANDATORY WORKFLOW:
  1. Run quality gates - Tests, linters, builds
  2. Commit changes - Meaningful commit message
  3. PUSH TO REMOTE - This is MANDATORY
  4. Verify - All changes committed AND pushed

---

Style Guidelines

风格指南

  1. Be direct - Get to the point quickly
  2. Be friendly - Welcome contributions
  3. Be concise - Avoid boilerplate
  4. Use tables - For commands, options, features
  5. Show examples - Code blocks over prose
  6. Link liberally - Cross-reference related docs
  1. 直接明了 - 尽快切入主题
  2. 友好热情 - 欢迎贡献
  3. 简洁精炼 - 避免冗余内容
  4. 使用表格 - 用于展示命令、选项、特性
  5. 提供示例 - 优先使用代码块而非文字描述
  6. 大量链接 - 交叉引用相关文档

Skill Boundaries

技能边界

DO:
  • Audit existing documentation
  • Generate standard OSS files
  • Validate documentation quality
DON'T:
  • Overwrite existing content without confirmation
  • Generate code documentation (use 
    $doc
    )
  • Create CI/CD files (use 
    $golden-init
    )
可执行操作：
  • 审核现有文档
  • 生成标准OSS文件
  • 验证文档质量
不可执行操作：
  • 未经确认覆盖现有内容
  • 生成代码文档（使用
    $doc
    ）
  • 创建CI/CD文件（使用
    $golden-init
    ）

Examples

示例

OSS Readiness Audit

OSS就绪性审核

User says: "Audit this repo for open-source documentation readiness."
What happens:
  1. Evaluate presence/quality of core OSS docs.
  2. Identify missing or weak sections.
  3. Output prioritized documentation actions.
用户指令： "Audit this repo for open-source documentation readiness."
执行流程：
  1. 评估核心OSS文档的存在情况/质量。
  2. 识别缺失或薄弱的部分。
  3. 输出按优先级排序的文档改进措施。

Scaffold Missing Docs

搭建缺失的文档

User says: "Generate missing OSS docs for this project."
What happens:
  1. Detect project type and documentation gaps.
  2. Scaffold standard files with project-aware content.
  3. Produce a checklist for final review and landing.
用户指令： "Generate missing OSS docs for this project."
执行流程：
  1. 检测项目类型和文档缺口。
  2. 搭建带有项目专属内容的标准文件。
  3. 生成最终审核和收尾的检查清单。

Troubleshooting

故障排查

ProblemCauseSolution
Generated docs feel genericProject signals too sparseAdd concrete repo context (commands, architecture, workflows)
Existing docs conflictLegacy text diverges from current behaviorReconcile with current code/process and mark obsolete sections
Contributor path unclearMissing setup/testing guidanceAdd explicit quickstart and validation commands
Open-source handoff incompleteSession-end workflow not reflectedAdd landing-the-plane and release hygiene steps
问题原因解决方案
生成的文档过于通用项目特征信息不足添加具体的仓库上下文（命令、架构、工作流）
现有文档存在冲突旧文本与当前行为不符与当前代码/流程对齐，并标记过时部分
贡献路径不清晰缺失安装/测试指南添加明确的快速入门和验证命令
开源交接不完整未体现会话收尾工作流添加「着陆流程」和发布规范步骤