Add SimpleDoc skill bundle

README.md

@@ -44,6 +44,16 @@ npx -y @simpledoc/simpledoc migrate
 
 This will start a step-by-step wizard to migrate existing documentation to SimpleDoc and add instructions to `AGENTS.md` to follow it.
 
+### Agent skill bundle
+
+SimpleDoc ships a bundled `simpledoc` skill for agent instructions. To install it into a repo-scoped Codex skill store:
+
+```bash
+npx -y @simpledoc/simpledoc --skill export simpledoc | skill-install --agent codex --scope repo
+```
+
+(`skill-install` is provided by the `skillflag` package.)
+
 ## CI / Enforcement
 
 To enforce SimpleDoc conventions in CI, add a step that fails when the repo needs migration:
@@ -88,7 +98,7 @@ The ISO 8601 date-prefixed format was inspired by the [Jekyll](https://jekyllrb.
 
 ## Examples
 
-For an example in this repo, see [docs/2025-12-22-created-simpledoc.md](docs/2025-12-22-created-simpledoc.md) and [docs/HOW_TO_DOC.md](docs/HOW_TO_DOC.md).
+For an example in this repo, see [docs/2025-12-22-created-simpledoc.md](docs/2025-12-22-created-simpledoc.md) and [skills/simpledoc/SKILL.md](skills/simpledoc/SKILL.md).
 
 ## License
 

docs/2025-12-22-created-simpledoc.md

@@ -10,4 +10,4 @@ At the beginning, I did not know how to communicate the solution easily while fi
 
 So I created this. I hope it helps you create order out of chaos in your `docs/` folder.
 
-This post is both a blog post intended to mark this event, and an example for SimpleDoc itself, together with [HOW_TO_DOC.md](./HOW_TO_DOC.md) in this folder.
+This post is both a blog post intended to mark this event, and an example for SimpleDoc itself, together with the bundled skill at [skills/simpledoc/SKILL.md](../skills/simpledoc/SKILL.md).

package.json

@@ -44,11 +44,13 @@
     "dist",
     "README.md",
     "LICENSE",
-    "docs"
+    "docs",
+    "skills"
   ],
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "commander": "^11.0.0"
+    "commander": "^11.0.0",
+    "skillflag": "^0.1.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",

docs/HOW_TO_DOC.md → skills/simpledoc/SKILL.md

@@ -1,21 +1,26 @@
-# Documentation Guidelines
-
 ---
+name: simpledoc
+description: Create or update documentation in this repo following SimpleDoc conventions.
+---
+
+# SimpleDoc Documentation Skill
+
+Use this skill whenever you are asked to create or update documentation in this repository.
 
 ## MUST DO SETUP
 
-**Attention agent!** This file is a template for creating instructions on how to create documentation in this repository. The placeholder sections should be filled in, before anything else.
+**Attention agent!** This section is a template for creating instructions on how to create documentation in this repository. The placeholder sections must be filled in before anything else.
 
 1. Fetch the most recent SimpleDoc specification from https://github.com/osolmaz/SimpleDoc and copy it below, replacing the placeholder content.
-2. Ask the user about their preferences in documentation style: Do they prefer a certain style of writing, a certain tone, a certain level of technicality, a certain way to create implementation plans, etc. Do a few rounds of back-and-forth to get the user's preferences, and use the output to populate the placeholder content in the Preferences in Documentation Style section.
+2. Ask the user about their preferences in documentation style (tone, technicality, planning style, etc.). Do a few rounds of back-and-forth to get the user's preferences, then replace the placeholder content in the Preferences section.
 
 After finishing the setup, DELETE ONLY this section between dividers `---`. The other agent instruction below is to be kept as is.
 
 ---
 
 **Attention agent!** Complete every item below before touching documentation work:
 
-1. **Read this file in full for the current session.** No shortcuts. Open `docs/HOW_TO_DOC.md`, refresh your memory, and only then proceed.
+1. **Read this file in full for the current session.** No shortcuts.
 2. **Verify that git is initialized and configured.** You will need the name and email of the current user in order to populate the `author` field in the YAML frontmatter. Run the following one-liner to verify:
 
 ```bash

src/bin/simpledoc.ts

@@ -1,4 +1,15 @@
 #!/usr/bin/env node
+import process from "node:process";
+import { handleSkillflag } from "skillflag/dist/index.js";
+
 import { runCli } from "../cli/index.js";
 
-await runCli(process.argv);
+const args = process.argv;
+if (args.includes("--skill")) {
+  const exitCode = await handleSkillflag(args, {
+    skillsRoot: new URL("../../skills/", import.meta.url),
+  });
+  process.exitCode = exitCode;
+} else {
+  await runCli(args);
+}

src/cli/migrate.ts

@@ -14,7 +14,7 @@ import {
 } from "../migrator.js";
 import {
   AGENTS_FILE,
-  HOW_TO_DOC_FILE,
+  SIMPLEDOC_SKILL_FILE,
   applyInstallationActions,
   buildInstallationActions,
   formatInstallActions,
@@ -149,14 +149,14 @@ function buildDefaultPreviews(opts: {
         actionCount: addLine.length,
       });
 
-    const howToDoc = opts.installActions.filter(
-      (a) => a.type === "write-file" && a.path === HOW_TO_DOC_FILE,
+    const skillTemplate = opts.installActions.filter(
+      (a) => a.type === "write-file" && a.path === SIMPLEDOC_SKILL_FILE,
     );
-    if (howToDoc.length > 0)
+    if (skillTemplate.length > 0)
       defaultPreviews.push({
-        title: `Create \`${HOW_TO_DOC_FILE}\` template`,
-        actionsText: formatInstallActions(howToDoc),
-        actionCount: howToDoc.length,
+        title: `Create \`${SIMPLEDOC_SKILL_FILE}\` template`,
+        actionsText: formatInstallActions(skillTemplate),
+        actionCount: skillTemplate.length,
       });
   }
 
@@ -193,7 +193,7 @@ export async function runMigrate(options: MigrateOptions): Promise<void> {
       createAgentsFile: !installStatus.agentsExists,
       addAttentionLine:
         installStatus.agentsExists && !installStatus.agentsHasAttentionLine,
-      addHowToDoc: !installStatus.howToDocExists,
+      addSkill: !installStatus.skillExists,
     });
 
     const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -408,8 +408,11 @@ export async function runMigrate(options: MigrateOptions): Promise<void> {
         summaryLines.push(`- Update \`${AGENTS_FILE}\` (add reminder line)`);
         continue;
       }
-      if (action.type === "write-file" && action.path === HOW_TO_DOC_FILE) {
-        summaryLines.push(`- Create \`${HOW_TO_DOC_FILE}\``);
+      if (
+        action.type === "write-file" &&
+        action.path === SIMPLEDOC_SKILL_FILE
+      ) {
+        summaryLines.push(`- Create \`${SIMPLEDOC_SKILL_FILE}\``);
         continue;
       }
     }

src/cli/steps/install.ts

@@ -2,18 +2,18 @@ import type { InstallationStatus } from "../../installer.js";
 import {
   AGENTS_ATTENTION_LINE,
   AGENTS_FILE,
-  HOW_TO_DOC_FILE,
+  SIMPLEDOC_SKILL_FILE,
 } from "../../installer.js";
 import { noteWrapped, promptConfirm } from "../ui.js";
 
 export async function runInstallSteps(status: InstallationStatus): Promise<{
   createAgentsFile: boolean;
   addAttentionLine: boolean;
-  addHowToDoc: boolean;
+  addSkill: boolean;
 } | null> {
   let createAgentsFile = false;
   let addAttentionLine = false;
-  let addHowToDoc = false;
+  let addSkill = false;
 
   if (!status.agentsExists) {
     noteWrapped(
@@ -36,18 +36,18 @@ export async function runInstallSteps(status: InstallationStatus): Promise<{
     addAttentionLine = include;
   }
 
-  if (!status.howToDocExists) {
+  if (!status.skillExists) {
     noteWrapped(
-      `Will create \`${HOW_TO_DOC_FILE}\` from the bundled SimpleDoc template (won't overwrite if it already exists).`,
-      "Proposed: Add docs/HOW_TO_DOC.md",
+      `Will create \`${SIMPLEDOC_SKILL_FILE}\` from the bundled SimpleDoc skill (won't overwrite if it already exists).`,
+      "Proposed: Add skills/simpledoc/SKILL.md",
     );
     const include = await promptConfirm(
-      `Create \`${HOW_TO_DOC_FILE}\` template?`,
+      `Create \`${SIMPLEDOC_SKILL_FILE}\` template?`,
       true,
     );
     if (include === null) return null;
-    addHowToDoc = include;
+    addSkill = include;
   }
 
-  return { createAgentsFile, addAttentionLine, addHowToDoc };
+  return { createAgentsFile, addAttentionLine, addSkill };
 }