SKILL.md
$27
Section
Purpose
Typical Content
Getting Started
Onboarding, first steps
Quick start, installation, first task
Guides / Tutorials
Step-by-step learning
How-to articles, workflows
Concepts
Background, architecture
Key concepts, glossary links
API Reference
Endpoint docs
Auth, request/response, examples; part of docs, not separate page
Troubleshooting
Problem solving
FAQ, common errors, support links
Best Practices
Information Architecture
- Progressive disclosure: Start simple, link to depth
- Sidebar navigation: Hierarchical, collapsible sections
- Search: Full-text search for long doc sets
- Breadcrumbs: For deep hierarchies
API Reference (within Docs)
API Reference is a section of docs, not a standalone page. Include: endpoints by resource, auth, request/response schemas, error codes, rate limits, code examples (cURL, SDKs). Use OpenAPI/Swagger for consistency.
Content
- Task-oriented: "How to X" not "X feature"
- Code examples: Copy-paste ready, multiple languages if relevant
- Screenshots/videos: For UI-heavy products
- Versioning: Document product/API version when applicable
SEO and Discovery
- Index docs: Unless internal-only; use robots if needed
- Internal links: Cross-link related articles, link to main site
- Schema: TechArticle, HowTo for guides
Output Format
- Structure (sections, hierarchy)
- Navigation design (sidebar, top-level)
- Getting Started outline
- Content checklist per section
- Subdomain/path recommendation
Related Skills
- api-page-generator: API intro page links to docs
- sidebar-generator: Docs sidebar design
- faq-page-generator: FAQ can live in docs or main site
- howto-section-generator: HowTo step blocks in guides/tutorials; TechArticle + HowTo alignment
- content-strategy: Doc content planning