[Skill Submission] skill-generalizer

skills/skill-generalizer/SKILL.md

@@ -36,11 +36,13 @@ Read the input skill and list every element that is specific to the original tea
 - Specific schedules or cron times
 - Specific URLs, API endpoints, or service accounts
 - Specific source lists (RSS feeds, databases, etc.)
-- Specific formatting preferences
+- Specific content values within message formatting (but keep the format structure itself — see note below)
 - Specific integration credentials or connection names
 - Specific file paths that assume a particular workspace layout
 - Specific content types or domains (e.g., "Every articles" becomes "content from your sources")
 
+**Important: preserve message formatting.** If the original skill defines how messages should be formatted (Slack markup, code block templates, specific structure for summaries, headers, links), keep that format structure intact. Only generalize the content values within it. The formatting is often what makes the skill's output good — stripping it produces generic, worse results.
+
 ### Step 2: Design onboarding questions
 
 For each hardcoded specific, decide whether it should become:
@@ -69,14 +71,14 @@ Rules for frontmatter:
 - `name` must be kebab-case, unique, and descriptive — used for file paths and internal references
 - `display_name` is the human-readable name shown on the dashboard (e.g., "News Updates" not "news-updates")
 - `description` is for humans on the dashboard — keep it clean and readable, no "Trigger when..." language
-- `onboarding: true` signals to the dashboard that this skill needs onboarding — the dashboard shows an "Onboard" button when this is present. When the bot removes this field after onboarding, the dashboard knows the user has completed setup.
+- `onboarding: true` signals to the dashboard that this skill needs onboarding — the dashboard shows an "Onboard" button when this is present. This field stays permanently; onboarding state is tracked in `memory/.onboarded-skills.md` instead.
 - `onboarding_prompt` is the Slack DM the bot sends when the user clicks that button — it must include the display name and jump straight into the first onboarding question. No fluff.
 
 ### Step 4: Write the skill body
 
-The skill body has two lifecycle states: **pre-onboarding** and **post-onboarding**. The pre-onboarding version ships with the skill. After onboarding completes, the bot rewrites the file to remove the onboarding section and fill in the user's configuration.
+The skill file is the same before and after onboarding — the `## Onboarding` section stays permanently. Onboarding state is tracked in `memory/.onboarded-skills.md`, not by modifying the skill file's structure. After onboarding, the bot fills in placeholder values in the config sections but leaves everything else intact.
 
-Write the **pre-onboarding version** following this structure:
+Write the skill following this structure:
 
 ```markdown
 # {Display Name}
@@ -89,7 +91,7 @@ Activate this skill when the user asks about {natural language phrases that woul
 
 ## Onboarding
 
-Remove this section after onboarding completes.
+**Before starting onboarding:** Check `memory/.onboarded-skills.md`. If `{skill-name}` is listed there, this skill is already onboarded — skip this section entirely and operate normally using the configured values below.
 
 1. {First onboarding question — be specific about what to ask and what answers to expect}
 2. {Second onboarding question}
@@ -103,10 +105,8 @@ Remove this section after onboarding completes.
 6. Iterate until the user is happy with the output. If the user requests any change, apply it and re-send the sample with the change visible. Do not finalize until the user explicitly confirms.
 7. Confirm setup with the user — summarize what was configured.
 8. Complete onboarding:
-   - Rewrite this SKILL.md file:
-     - Remove the `onboarding: true` and `onboarding_prompt` fields from the frontmatter
-     - Remove the entire `## Onboarding` section
-     - Fill in the user's answers directly in the relevant sections below (sources, schedule, format, etc.)
+   - Fill in the user's answers directly in the relevant sections below (sources, schedule, format, etc.)
+   - Add `{skill-name}` to `memory/.onboarded-skills.md` (create the file if it doesn't exist)
    - {If a cron job was configured: "Create the cron job with the user's chosen schedule."}
 
 ### Onboarding behavior rules
@@ -139,15 +139,16 @@ Before outputting the final skill, verify:
 - [ ] Onboarding includes an iteration loop — the user can tweak until happy, and every change re-sends the sample for confirmation
 - [ ] Onboarding does not parrot back what the user just said — accept clear answers and move on
 - [ ] Onboarding never shows internal dialogue (state files, memory paths, user IDs, implementation details)
-- [ ] Onboarding completion removes `onboarding: true`, `onboarding_prompt`, and the `## Onboarding` section from the file
+- [ ] The `## Onboarding` section starts with a gate check against `memory/.onboarded-skills.md`
+- [ ] Onboarding completion adds the skill to `memory/.onboarded-skills.md` and fills in config sections — does NOT remove onboarding fields or the onboarding section
 - [ ] The `onboarding_prompt` includes the display name and the first question
 - [ ] The `description` is clean and human-readable (no trigger hints)
 - [ ] The `display_name` is present and human-readable
 - [ ] Trigger conditions are in a `## Trigger` section in the body, not in the description
 - [ ] All delivery is via Slack DM (no "where should I deliver" questions)
 - [ ] The skill has a Customization section
-- [ ] Post-onboarding, the skill is fully self-contained — no external config files, everything lives in the skill file
-- [ ] No references to `memory/` config files — all config is stored directly in the skill file
+- [ ] Message formatting from the original skill is preserved (keep the format structure, generalize only the content values)
+- [ ] Operational state files (`memory/*.json`) are fine for runtime data; config sections in the skill file hold user preferences
 
 ## Example transformation
 
@@ -172,11 +173,14 @@ onboarding_prompt: "Let's get you set up with Content Digest. What sources would
 Activate this skill when the user asks about news updates, content alerts, article digests, or monitoring sources for new content.
 
 ## Onboarding
+
+**Before starting onboarding:** Check `memory/.onboarded-skills.md`. If `content-digest` is listed there, skip this section entirely.
+
 1. Ask what sources to monitor (RSS feeds, websites, etc.)
 2. Ask when they want updates (e.g., "every morning at 8am", "twice a day")
 3. Test: fetch the sources now, generate a sample digest, show it to the user
 4. Iterate: let them tweak sources, format, or anything else
-5. Confirm and rewrite this file: remove onboarding section and frontmatter, fill in sources and schedule
+5. Confirm and complete: fill in sources and schedule sections below, add `content-digest` to `memory/.onboarded-skills.md`
 6. Create the cron job with their schedule
 
 ## Sources
@@ -196,8 +200,9 @@ Change sources, schedule, or format anytime by asking. Updates go directly into
 
 Some things should stay as-is:
 - References to Plus One platform features (cron jobs, memory files, Slack delivery)
-- The onboarding completion protocol (rewriting the skill file to remove onboarding fields)
-- Slack message formatting conventions (platform-level, not team-specific)
+- The onboarding completion protocol (adding the skill to `memory/.onboarded-skills.md` and filling in config sections — never removing onboarding instructions from the skill file)
+- Slack message formatting conventions and structure (platform-level, not team-specific)
+- Message format templates from the original skill — keep the structure, generalize only the content values
 - Delivery is always Slack DM — do not ask where to deliver
 
 ## Output format