oss-docs

OSS ドキュメントスキル

オープンソースプロジェクトのドキュメントを作成し、監査します。

概要

このスキルは、次の作業を通じて、オープンソースとして公開するためのリポジトリの準備を支援します。

1. 既存ドキュメントの完全性を監査する
2. 不足している標準ファイルを作成する
3. プロジェクトの種類に合わせたコンテンツを生成する

コマンド

コマンド	操作
audit	存在する OSS ドキュメントと不足している OSS ドキュメントを確認します
scaffold	不足している標準ファイルをすべて作成します
scaffold [file]	指定したファイルを作成します
update	最新のパターンに合わせて既存ドキュメントを更新します
validate	ドキュメントがベストプラクティスに従っているか確認します

---

フェーズ 0：プロジェクトの検出

# 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")

# 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

---

サブコマンド：audit

必須ファイル（Tier 1 - コア）

ファイル	目的
LICENSE	法的条件
README.md	プロジェクトの概要
CONTRIBUTING.md	貢献方法
CODE_OF_CONDUCT.md	コミュニティ基準

推奨ファイル（Tier 2 - 標準）

ファイル	目的
SECURITY.md	脆弱性の報告
CHANGELOG.md	バージョン履歴
AGENTS.md	AI アシスタント向けコンテキスト
.github/ISSUE_TEMPLATE/	Issue テンプレート
.github/PULL_REQUEST_TEMPLATE.md	PR テンプレート

任意のファイル（Tier 3 - 拡張）

ファイル	必要となる場合
docs/QUICKSTART.md	セットアップが複雑な場合
docs/ARCHITECTURE.md	コードベースが単純でない場合
docs/CLI_REFERENCE.md	CLI ツールがある場合
docs/CONFIG.md	設定可能なソフトウェアの場合
examples/	複雑なワークフローの場合

---

サブコマンド：scaffold

テンプレートの選択

プロジェクトの種類	重点項目
cli	インストール、コマンド、例
operator	K8s CRD、RBAC、デプロイ
service	API、設定、デプロイ
library	API リファレンス、例
helm	値、依存関係、アップグレード

---

ドキュメントの構成

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 のパターン

# Agent Instructions

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

## Quick Reference

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

締めくくり（セッションの完了）

必須のワークフロー：

1. 品質ゲートを実行する - テスト、リンター、ビルド
2. 変更をコミットする - 意味のあるコミットメッセージ
3. リモートにプッシュする - これは必須です
4. 確認する - すべての変更がコミットされ、プッシュされていること

---

## 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

---

## 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 (out of scope — configure CI/CD separately)

## Examples

### OSS Readiness Audit

**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.

### 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.

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| Generated docs feel generic | Project signals too sparse | Add concrete repo context (commands, architecture, workflows) |
| Existing docs conflict | Legacy text diverges from current behavior | Reconcile with current code/process and mark obsolete sections |
| Contributor path unclear | Missing setup/testing guidance | Add explicit quickstart and validation commands |
| Open-source handoff incomplete | Session-end workflow not reflected | Add landing-the-plane and release hygiene steps |

## Reference Documents

- [references/beads-patterns.md](references/beads-patterns.md)
- [references/documentation-tiers.md](references/documentation-tiers.md)
- [references/project-types.md](references/project-types.md)