docs: rewrite documentation and add docs-writing skill

Author: MrPunyapal

README.md

@@ -31,12 +31,12 @@ Docsmith is designed for package and project documentation where you want a fast
 composer require --dev mrpunyapal/docsmith
 ```
 
-Using AI agents (Claude Code, Cursor, Boost, ...)? Docsmith ships an installable skill:
+Using AI agents (Claude Code, Cursor, Boost, ...)? Docsmith ships installable skills:
 
 ```bash
 npx skills add MrPunyapal/docsmith/resources/boost/skills
 # or, in a Laravel project with Boost:
-php artisan boost:install   # installs it automatically from composer.json
+php artisan boost:install   # installs them automatically from composer.json
 ```
 
 ## Quick Start

docs/export/docs.md

@@ -409,9 +409,14 @@ MIT. See [LICENSE](https://github.com/MrPunyapal/docsmith/blob/main/LICENSE) for
 composer require --dev mrpunyapal/docsmith
 ```
 
-## Install the AI agent skill
+## Install the AI agent skills
 
-Docsmith ships an [Agent Skills](https://agentskills.io) compatible skill called `docsmith-development`. It teaches coding agents such as Claude Code, Cursor, Codex, and OpenCode how to use the package: build options, frontmatter keys, versioned docs, docs hubs, and remote source syncing.
+Docsmith ships two [Agent Skills](https://agentskills.io) compatible skills:
+
+- `docsmith-development`: teaches agents the package itself, build options, frontmatter keys, versioned docs, docs hubs, remote source syncing, and Open Graph images.
+- `docs-writing`: teaches agents how to write documentation pages that build cleanly and read well.
+
+They work with coding agents such as Claude Code, Cursor, Codex, and OpenCode.
 
 ### Via Laravel Boost
 
@@ -435,7 +440,7 @@ Any agent supported by the [skills CLI](https://skills.sh) can install it too:
 npx skills add MrPunyapal/docsmith/resources/boost/skills
 ```
 
-After installing, ask your agent to activate the `docsmith-development` skill when it works on documentation builds.
+After installing, ask your agent to activate the `docsmith-development` skill when it works on documentation builds, and `docs-writing` when it writes or edits documentation pages.
 
 ## Build documentation
 
@@ -856,7 +861,7 @@ hidden: true
 
 ## LLM export
 
-Docsmith generates three text files for LLM consumption: `llms.txt`, `llms-full.txt`, and `export/docs.md`. This is enabled by default; see [LLM Export](llm-export.md).
+Docsmith generates three text files for LLM consumption: `llms.txt`, `llms-full.txt`, and `export/docs.md`. This is enabled by default; see [LLM Export](llm-export.md) for details.
 
 ## Attribution badge
 
@@ -894,6 +899,16 @@ If the source directory has no `index.md`, Docsmith generates a landing page aut
 
 Every build also writes `search-index.json`, `sitemap.xml`, `.nojekyll`, and the LLM export files into the output directory.
 
+## Linking between pages
+
+Write internal links the GitHub way, pointing at the `.md` file:
+
+```markdown
+See [Versioned Docs](versioned-docs.md) for details.
+```
+
+Docsmith rewrites these to the built page URLs at build time. Relative paths (`../installation.md`) and fragments (`configuration.md#options`) both resolve, in plain builds as well as versioned and hub builds. Links to `.md` files that are not part of the build are left untouched, as are external URLs and anchors.
+
 ## README index compatibility mode
 
 Docsmith can import README index formats used by projects like `laravel-undocumented` and `laravel-attributes-list`:

docs/index.html

@@ -85,16 +85,16 @@ <h2 id="quick-start">Quick start</h2>
 <p>This reads Markdown from <code>md/</code> and writes the site to <code>docs/</code> by default, which works directly with GitHub Pages.</p>
 <h2 id="documentation">Documentation</h2>
 <ul>
-<li><a href="installation.md">Installation</a></li>
-<li><a href="usage.md">Usage</a></li>
-<li><a href="versioned-docs.md">Versioned Docs</a></li>
-<li><a href="docs-hub.md">Docs Hub</a></li>
-<li><a href="remote-sources.md">Remote Sources</a></li>
-<li><a href="workflows.md">Workflows</a></li>
-<li><a href="llm-export.md">LLM Export</a></li>
-<li><a href="open-graph.md">Open Graph Images</a></li>
-<li><a href="architecture.md">Architecture</a></li>
-<li><a href="development.md">Development</a></li>
+<li><a href="installation/">Installation</a></li>
+<li><a href="usage/">Usage</a></li>
+<li><a href="versioned-docs/">Versioned Docs</a></li>
+<li><a href="docs-hub/">Docs Hub</a></li>
+<li><a href="remote-sources/">Remote Sources</a></li>
+<li><a href="workflows/">Workflows</a></li>
+<li><a href="llm-export/">LLM Export</a></li>
+<li><a href="open-graph/">Open Graph Images</a></li>
+<li><a href="architecture/">Architecture</a></li>
+<li><a href="development/">Development</a></li>
 </ul>
 <h2 id="license">License</h2>
 <p>MIT. See <a href="https://github.com/MrPunyapal/docsmith/blob/main/LICENSE">LICENSE</a> for details.</p>

docs/installation/index.html

@@ -57,8 +57,13 @@ <h2 id="requirements">Requirements</h2>
 <h2 id="install-the-package">Install the package</h2>
 <pre class="phiki language-shellscript github-light phiki-themes github-dark" data-language="shellscript" style="background-color: #fff;color: #24292e;--phiki-dark-background-color: #24292e;--phiki-dark-color: #e1e4e8;"><code><span class="line"><span class="token" style="color: #6f42c1;--phiki-dark-color: #b392f0;">composer</span><span class="token"> </span><span class="token" style="color: #032f62;--phiki-dark-color: #9ecbff;">require</span><span class="token"> </span><span class="token" style="color: #005cc5;--phiki-dark-color: #79b8ff;">-</span><span class="token" style="color: #005cc5;--phiki-dark-color: #79b8ff;">-dev</span><span class="token"> </span><span class="token" style="color: #032f62;--phiki-dark-color: #9ecbff;">mrpunyapal/docsmith</span><span class="token">
 </span></span></code></pre>
-<h2 id="install-the-ai-agent-skill">Install the AI agent skill</h2>
-<p>Docsmith ships an <a href="https://agentskills.io">Agent Skills</a> compatible skill called <code>docsmith-development</code>. It teaches coding agents such as Claude Code, Cursor, Codex, and OpenCode how to use the package: build options, frontmatter keys, versioned docs, docs hubs, and remote source syncing.</p>
+<h2 id="install-the-ai-agent-skills">Install the AI agent skills</h2>
+<p>Docsmith ships two <a href="https://agentskills.io">Agent Skills</a> compatible skills:</p>
+<ul>
+<li><code>docsmith-development</code>: teaches agents the package itself, build options, frontmatter keys, versioned docs, docs hubs, remote source syncing, and Open Graph images.</li>
+<li><code>docs-writing</code>: teaches agents how to write documentation pages that build cleanly and read well.</li>
+</ul>
+<p>They work with coding agents such as Claude Code, Cursor, Codex, and OpenCode.</p>
 <h3 id="via-laravel-boost">Via Laravel Boost</h3>
 <p>If your Laravel project uses <a href="https://laravel.com/docs/boost">Boost</a>, the skill installs automatically because Docsmith is in your <code>composer.json</code>:</p>
 <pre class="phiki language-shellscript github-light phiki-themes github-dark" data-language="shellscript" style="background-color: #fff;color: #24292e;--phiki-dark-background-color: #24292e;--phiki-dark-color: #e1e4e8;"><code><span class="line"><span class="token" style="color: #6f42c1;--phiki-dark-color: #b392f0;">php</span><span class="token"> </span><span class="token" style="color: #032f62;--phiki-dark-color: #9ecbff;">artisan</span><span class="token"> </span><span class="token" style="color: #032f62;--phiki-dark-color: #9ecbff;">boost:install</span><span class="token">
@@ -70,7 +75,7 @@ <h3 id="via-the-skills-cli">Via the skills CLI</h3>
 <p>Any agent supported by the <a href="https://skills.sh">skills CLI</a> can install it too:</p>
 <pre class="phiki language-shellscript github-light phiki-themes github-dark" data-language="shellscript" style="background-color: #fff;color: #24292e;--phiki-dark-background-color: #24292e;--phiki-dark-color: #e1e4e8;"><code><span class="line"><span class="token" style="color: #6f42c1;--phiki-dark-color: #b392f0;">npx</span><span class="token"> </span><span class="token" style="color: #032f62;--phiki-dark-color: #9ecbff;">skills</span><span class="token"> </span><span class="token" style="color: #032f62;--phiki-dark-color: #9ecbff;">add</span><span class="token"> </span><span class="token" style="color: #032f62;--phiki-dark-color: #9ecbff;">MrPunyapal/docsmith/resources/boost/skills</span><span class="token">
 </span></span></code></pre>
-<p>After installing, ask your agent to activate the <code>docsmith-development</code> skill when it works on documentation builds.</p>
+<p>After installing, ask your agent to activate the <code>docsmith-development</code> skill when it works on documentation builds, and <code>docs-writing</code> when it writes or edits documentation pages.</p>
 <h2 id="build-documentation">Build documentation</h2>
 <p>Docsmith builds a static site from any Markdown directory, either from PHP or from the command line.</p>
 <h3 id="command-line">Command line</h3>
@@ -97,7 +102,7 @@ <h3 id="php">PHP</h3>
             </article>
             <nav class="pager" aria-label="Page navigation"><a class="pager-link" href="../"><span>Previous</span><strong>Docsmith</strong></a><a class="pager-link pager-link-next" href="../usage/"><span>Next</span><strong>Usage</strong></a></nav>
         </main>
-        <aside class="toc-sidebar" data-docsmith-toc><p class="toc-title">On this page</p><nav class="toc-links"><a class="toc-link toc-link-level-2" href="#requirements" data-docsmith-toc-link="requirements">Requirements</a><a class="toc-link toc-link-level-2" href="#install-the-package" data-docsmith-toc-link="install-the-package">Install the package</a><a class="toc-link toc-link-level-2" href="#install-the-ai-agent-skill" data-docsmith-toc-link="install-the-ai-agent-skill">Install the AI agent skill</a><a class="toc-link toc-link-level-3" href="#via-laravel-boost" data-docsmith-toc-link="via-laravel-boost">Via Laravel Boost</a><a class="toc-link toc-link-level-3" href="#via-the-skills-cli" data-docsmith-toc-link="via-the-skills-cli">Via the skills CLI</a><a class="toc-link toc-link-level-2" href="#build-documentation" data-docsmith-toc-link="build-documentation">Build documentation</a><a class="toc-link toc-link-level-3" href="#command-line" data-docsmith-toc-link="command-line">Command line</a><a class="toc-link toc-link-level-3" href="#php" data-docsmith-toc-link="php">PHP</a></nav></aside>
+        <aside class="toc-sidebar" data-docsmith-toc><p class="toc-title">On this page</p><nav class="toc-links"><a class="toc-link toc-link-level-2" href="#requirements" data-docsmith-toc-link="requirements">Requirements</a><a class="toc-link toc-link-level-2" href="#install-the-package" data-docsmith-toc-link="install-the-package">Install the package</a><a class="toc-link toc-link-level-2" href="#install-the-ai-agent-skills" data-docsmith-toc-link="install-the-ai-agent-skills">Install the AI agent skills</a><a class="toc-link toc-link-level-3" href="#via-laravel-boost" data-docsmith-toc-link="via-laravel-boost">Via Laravel Boost</a><a class="toc-link toc-link-level-3" href="#via-the-skills-cli" data-docsmith-toc-link="via-the-skills-cli">Via the skills CLI</a><a class="toc-link toc-link-level-2" href="#build-documentation" data-docsmith-toc-link="build-documentation">Build documentation</a><a class="toc-link toc-link-level-3" href="#command-line" data-docsmith-toc-link="command-line">Command line</a><a class="toc-link toc-link-level-3" href="#php" data-docsmith-toc-link="php">PHP</a></nav></aside>
     </div>
     <div class="search-overlay" data-docsmith-search-overlay hidden role="dialog" aria-label="Search documentation">
     <div class="search-overlay-backdrop" data-docsmith-search-overlay-close></div>