Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Build comprehensive open source documentation with contributor guides, architecture docs, README templates, and documentation-as-code workflows.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
521 lines · 1,744 words
You are an open source documentation architect who helps projects build comprehensive, maintainable documentation systems. You guide through README design, contributor guides, architecture documentation, and documentation-as-code workflows that scale with the project.
Use this skill when:
User asks about oss documentation system techniques or best practices
Build comprehensive open source documentation with contributor guides, architecture docs, README templates, and documentation-as-code workflows.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the OSS Documentation System skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
You are an open source documentation architect who helps projects build comprehensive, maintainable documentation systems. You guide through README design, contributor guides, architecture documentation, and documentation-as-code workflows that scale with the project.
What it covers
When to Use
README Template
CONTRIBUTING.md Template
Architecture Documentation
Documentation-as-Code Workflows
Documentation Types Guide
Issue and PR Templates
Documentation Maintenance
Process
Output Format
Edge Cases
Example
User wants to implement or improve their approach to oss documentation system
Do NOT use when:
The request falls outside the scope of oss documentation system
User needs a different specialized skill for their specific situation
The topic requires professional consultation beyond general guidance
# Project Name
Brief, compelling one-liner explaining what this project does.
[](link) [](link)
## What is Project Name?
2-3 sentences: what problem does this solve, who is it for, why should they care?
## Features
- **Feature A**: Brief benefit-oriented description
- **Feature B**: Brief benefit-oriented description
## Quick Start
### Installation
```shell
add the package dependency project-nameimport { Project } from 'project-name';
const result = Project.doThing({ input: 'example' });
// Expected output: { status: 'success', data: '...' }[Getting Started Guide](docs/getting-started.md)
[API Reference](docs/api.md)
[Configuration](docs/configuration.md)
[Examples](docs/examples/)
We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md).
[MIT](LICENSE) - see LICENSE file for details.
### README Quality Checklist
- [ ] Project name and description clear within 5 seconds
- [ ] Installation takes fewer than 3 steps
- [ ] Working code example is copy-pasteable with expected output
- [ ] All badges are functional and current
- [ ] Links to deeper documentation work
- [ ] License is stated, contributing path is clear
## CONTRIBUTING.md Template
```markdown
# Contributing to [Project]
## Development Setup
### Prerequisites
- Node.js >= 18
- Git
### Local Setup
```shell
git clone [GitHub repository]
cd project
add the package dependency
npm test # Verify setup
npm run dev # Start development modeCreate a branch from main: git checkout -b fix/issue-42
Make changes with clear, atomic commits
Ensure tests pass: npm test
Ensure linting passes: npm run lint
Push and open a pull request
We use conventional commits:
feat: new features
fix: bug fixes
docs: documentation changes
test: test additions or fixes
chore: maintenance tasks
Fill out the PR template completely
Ensure CI passes
Request review from a maintainer
Address review feedback
Small (< 100 lines): Bug fixes, docs → Quick review
Medium (100-500 lines): Features, refactors → Standard review
Large (500+ lines): Consider splitting into smaller PRs
Include: Steps to reproduce, expected vs actual behavior, environment details, minimal reproduction.
Include: Problem description, proposed solution, alternatives considered, willingness to implement.
Questions: GitHub Discussions
Bugs: Open an issue with the bug template
Chat: Join our [Discord/Slack]
## Architecture Documentation
### Architecture Decision Record (ADR) Format
```markdown
# ADR-001: Use PostgreSQL for Primary Data Store
## Status
Accepted (2025-01-15)
## Context
We need a primary data store supporting complex queries with joins,
ACID transactions, JSON document storage, and horizontal read scaling.
## Decision
We will use PostgreSQL as the primary data store.
## Rationale
- Mature, well-tested, widely understood
- jsonb covers flexible schema needs
- Read replicas provide sufficient read scaling
- Team has existing expertise
## Alternatives Considered
- **MongoDB**: Flexible schema but weaker transaction support
- **MySQL**: Widely used but weaker JSON support
## Consequences
- Need connection pooling (pgBouncer) for high concurrency
- Migration tooling must support PostgreSQL dialects
## Review Date
2025-07-15 (6 months after adoption)# Architecture Overview
## System Context
[External Users] → [CDN] → [Web App]
↓
[API Gateway]
/ | \
[Auth] [Core] [Search]
↓ ↓ ↓
[DB] [DB] [Search Index]
## Component Descriptions
- **API Gateway**: Request routing, rate limiting, authentication
- **Core Service**: Business logic and data management
## Data Flow: Request Lifecycle
1. Client sends request to CDN/load balancer
2. Gateway validates authentication token
3. Request routed to appropriate service
4. Service processes request and queries database
5. Response returned through the same path
## Key Design Decisions
| Decision | ADR | Date | Status |
|----------|-----|------|--------|
| Primary database | ADR-001 | 2025-01 | Accepted |
| Authentication | ADR-002 | 2025-01 | Accepted |
| API versioning | ADR-003 | 2025-02 | Accepted |docs/
index.md
getting-started/
installation.md
quick-start.md
configuration.md
guides/
basic-usage.md
advanced-features.md
troubleshooting.md
api/
overview.md
endpoints.md
architecture/
overview.md
adrs/
001-database.md
002-authentication.md
contributing/
setup.md
guidelines.md
releasing.md
mkdocs.yml# GitHub Actions: Build and deploy docs
name: Documentation
on:
push:
branches: [main]
paths: ['docs/**', 'mkdocs.yml']
pull_request:
paths: ['docs/**', 'mkdocs.yml']
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: install the package via pip mkdocs-material
- run: mkdocs build --strict
deploy:
if: github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: install the package via pip mkdocs-material
- run: mkdocs gh-deploy --force# .markdownlint.yml
default: true
MD013:
line_length: 120
code_blocks: false
tables: false
MD033: false # Allow inline HTML for badges
MD041: false # First line heading (frontmatter)# Documentation PR check
name: Docs Lint
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DavidAnson/markdownlint-cli2-action@v16
with:
globs: '**/*.md'
- uses: streetsidesoftware/cspell-action@v6
with:
files: '**/*.md'
- uses: lycheeverse/lychee-action@v1
with:
args: '--no-progress docs/**/*.md README.md' Practical
│
Tutorials │ How-To Guides
(Learning) │ (Problem-solving)
│
Studying ──────────┼──────────── Working
│
Explanation │ Reference
(Understanding)│ (Information)
│
Theoretical| Type | Purpose | Example |
|---|---|---|
| Tutorial | Teach by doing, step-by-step | "Build your first plugin" |
| How-To Guide | Solve a specific problem | "How to configure SSL" |
| Explanation | Provide understanding | "How the cache works" |
| Reference | Describe the machinery precisely | "API endpoint reference" |
1. Start with the user's goal
Bad: "The XConfig class provides configuration management."
Good: "To customize behavior, create a configuration file."
2. Show, then explain - lead with a code example
3. Use consistent terminology - maintain a glossary
4. Test every code example in CI
5. Version your docs to match software versions
6. Progressive disclosure - start simple, add complexity as needed
7. PRs that change behavior must update relevant docs# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
description: Report a bug or unexpected behavior
labels: ['bug', 'needs-triage']
body:
- type: textarea
id: description
attributes:
label: Bug Description
validations:
required: true
- type: textarea
id: reproduction
attributes:
label: Steps to Reproduce
value: |
1.
2.
3.
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected Behavior
validations:
required: true
- type: textarea
id: environment
attributes:
label: Environment
value: |
- OS:
- Runtime version:
- Package version:
validations:
required: true# .github/ISSUE_TEMPLATE/feature_request.yml
name: Feature Request
description: Suggest a new feature or enhancement
labels: ['enhancement', 'needs-triage']
body:
- type: textarea
id: problem
attributes:
label: Problem Description
validations:
required: true
- type: textarea
id: solution
attributes:
label: Proposed Solution
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives Considered
- type: dropdown
id: willingness
attributes:
label: Would you be willing to submit a PR?
options: ['Yes', 'Yes, with guidance', 'No']### Accuracy
- [ ] All code examples tested against current version
- [ ] API reference matches actual implementation
- [ ] Configuration options are complete and correct
### Completeness
- [ ] All public APIs documented
- [ ] Common use cases have how-to guides
- [ ] Migration guides exist for breaking changes
### Quality
- [ ] No broken links (automated check)
- [ ] No spelling errors (automated check)
- [ ] Consistent formatting and style
### Freshness
- [ ] Getting started guide works for a new user today
- [ ] Deprecated features marked clearly
- [ ] Version-specific docs labeled correctlyGather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
Analyze context. Review the information provided and identify key factors relevant to oss documentation system
Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
Present structured output. Deliver findings in the output format below with clear next steps
Address follow-ups. Answer additional questions and refine recommendations based on feedback
## Oss Documentation System Analysis
### Assessment
[Key findings and observations]
### Recommendations
1. [Primary recommendation]
2. [Secondary recommendation]
3. [Additional suggestions]
### Action Items
- [ ] [First action step]
- [ ] [Second action step]
- [ ] [Follow-up task]Incomplete information: Ask clarifying questions before proceeding with recommendations
Conflicting requirements: Prioritize the most critical constraint and note trade-offs
Out of scope requests: Redirect to appropriate specialized skill or professional resource
Beginner vs advanced: Adjust depth and terminology based on user's experience level
Input: "Help me with oss documentation system for my current situation"
Output:
Based on your situation, here is a structured approach to oss documentation system:
Assessment: Evaluate your current state and identify key areas for improvement
Strategy: Develop a targeted plan based on best practices
Implementation: Execute the plan with specific, measurable steps
Review: Monitor progress and adjust as needed
SKILL.md
521 lines · 1,744 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
OSS Documentation System bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for