Session To Skill And Blog

session-to-skill-and-blog

Turn session evidence into the appropriate durable outputs:

• a blog that explains the experience, reasoning, and conclusion;
• zero or more skills that let a future agent execute reusable capabilities;
• project documentation for facts and conventions that remain local.

Do not force a one-to-one pair. One blog may attach no skill, one skill, or several skills; one skill may support several later blogs. The outputs share evidence, not structure.

Confirm authoring choices, then classify. For every accepted skill candidate, author and push the skill before writing the blog. This preserves the operational contract before narrative compression. If intake said no skill, or no candidate passes the skill gate, write the blog without inventing a skill.

References

This file is a thin index. Load the matching reference when you start the actual work:

For LiteXML tag syntax itself, load the litexml-authoring skill (fresh via load-litexml.sh) — this skill governs whether/when, that one governs how.

Configuration

~/.config/innei-skills/config.json (see references/config.example.json):

{ "skill_repo_dir": "~/git/innei-repo/SKILL" }

Missing key → fallback to ~/git/innei-repo/SKILL. Domains: infrastructure / automation / writing / research / content. Prereqs once per machine: npm i -g @mx-space/cli (Node ≥ 22, ≥ 0.16.0 — check mxs draft --help and mxs author --help); mxs auth login.

Scripts

Define $S once per session. Search known locations; the first that contains resolve-skill-repo.sh wins:

S=""
for cand in \
  "$HOME/.claude/skills/session-to-skill-and-blog/scripts" \
  "$HOME/.codex/skills/session-to-skill-and-blog/scripts" \
  "$HOME/.agents/skills/session-to-skill-and-blog/scripts" \
  "$(git rev-parse --show-toplevel 2>/dev/null)/.claude/skills/session-to-skill-and-blog/scripts" \
  "$(git rev-parse --show-toplevel 2>/dev/null)/.agent/skills/session-to-skill-and-blog/scripts" \
  "$(git rev-parse --show-toplevel 2>/dev/null)/skills/automation/session-to-skill-and-blog/scripts"
do
  [ -n "$cand" ] && [ -f "$cand/resolve-skill-repo.sh" ] && {
    S="$(cd "$cand" && pwd)"; break
  }
done
[ -n "$S" ] || { echo "error: cannot locate session-to-skill-and-blog/scripts" >&2; exit 1; }
REPO="$(bash "$S/resolve-skill-repo.sh")"

Workflow

[0] Confirm persona and skill pairing (interactive tool if available)
[1] Inventory and classify session evidence
[2] State and evaluate each capability thesis
       intake = none ──> skip to [5]
       rejected ──> blog or project documentation
       accepted ──> one coherent skill
[3] Scaffold, author, validate, commit, and push accepted skills
[4] Push accepted skills to mx-core and collect their ids
[5] Write the blog from the narrative evidence
[6] Publish via mxs with zero or more --skill-id arguments

[0] Confirm authoring choices

Do this before [1]. If the triggering message already answered both questions, record those answers and continue. Otherwise ask, then wait.

If the runtime has an interactive question tool (AskUserQuestion, ask_user_question, or equivalent), ask both questions in one call. If no such tool exists, ask the same two questions in chat. Do not start [1] until both answers are recorded.

Ask in Chinese. Map the answers as follows; do not invent extra questions.

1. 你想用哪种写作人格去编写这篇文章？

   Option	Record as	Meaning
   Agent 第一人称	agent	「我」是 agent
   站长第一人称	site-owner	「我」是站长
   中性叙述	neutral	不用「我」
   看材料再定	defer	Choose after the spine

   Narrator attribution lives in writing-style.md. A custom "Other" answer maps to the closest of these four, or follows the user's wording when it already names a narrator.

2. 这篇文章需要搭配一个 skill 吗？

   Option	Record as	Effect
   需要	required	Run [2]–[4]; a failing gate still yields a blog without a skill
   不需要	none	Skip [2]–[4]; write the blog only
   看材料再定	defer	Existing semantic gate decides

A recorded agent / site-owner / neutral overrides the spine default in writing-style.md. none skips skill work even if a candidate would pass.

[1] Inventory and classify

Collect decision points, failed assumptions, symptom-to-cause evidence, commands, reusable procedures, safety boundaries, verification results, and project-local facts. Classify each item by its future function:

Treat code or configuration length only as a resource-planning signal. It is not evidence that a skill should exist.

[2] State and evaluate the capability thesis

If intake recorded none, skip this step and [3]–[4].

Write this sentence before scaffolding a candidate:

This skill helps an agent [action] [target] when [trigger], while preserving [constraint], and verifies success through [observable outcome].

Reject or redirect the candidate unless every gate passes:

Name accepted skills with a concise, verb-led target and action. Prefer split-dokploy-traffic-safely over traefik-notes, and migrate-nextjs-rsc-under-cdn-constraints over nextjs-migration.

Keep one capability thesis per skill. Split candidates when their triggers, targets, or completion criteria can vary independently. Place cross-project capabilities in this repository; place facts that only future work in one repository needs in that repository's agent or project documentation.

Plan bundled resources by function, not by arbitrary line count:

Do not create empty resource directories.

[3] Scaffold, author, and push accepted skills

bash "$S/scaffold-skill.sh" <domain> <skill-name> "<one-line purpose>"

Use the scaffold once for each accepted capability. Author the skill as an execution interface for a future agent, not as a compressed version of the blog.

Every generated skill requires this contract:

Add the following sections only when they carry real operational information:

Do not emit empty sections to satisfy a template. Do not repeat generic technical knowledge. Keep the main file below 500 lines and use progressive disclosure for details.

Validate each folder with the available skill validator before committing. Then commit and push the accepted skill:

cd "$REPO" && git add "skills/<domain>/<skill-name>" && git commit -m "feat: add <skill-name> skill" && git push

The pre-commit hook enforces: README row exists inside the matching domain table; both flat symlinks present and resolved. Skill URL (for reference only — never mentioned in the blog body; the skill card carries the linkage): https://github.com/Innei/SKILL/tree/main/skills/<domain>/<skill-name>

[4] Push accepted skills to mx-core

For every accepted skill, push its SKILL.md to mx-core's snippet store so the reader-facing <SkillCardList> can render it and the public raw URL (${MXS_API_URL}/api/v3/s/sk/<name>) exists.

SKILL_ID=$(bash "$S/push-skill.sh" "$REPO/skills/<domain>/<skill-name>/SKILL.md")

Run the command once per skill and retain every returned id. The script is idempotent — mxs snippet put upserts by path. Sibling asset files are pushed as --type text under sk/<name>/ — the backend rejects --type skill for any path not ending in /SKILL.md, and without them relative links inside SKILL.md 404 on the public site. Capture the returned id; step [6] threads it through create-draft.sh.

If a skill never reaches mx-core, the blog may still publish without that install card. If no skill candidate passed the gate, skip this step entirely.

[5] Write the blog

Load writing-style.md, node-usage.md, and visuals.md before drafting. Do not restate those rules here.

Use the recorded narrator. If intake recorded defer, choose after the spine per writing-style.md.

After choosing the reader contract and article spine, derive a working title and stable slug. Finalize the title after the draft proves its central claim; do not allow a sharper generalization to erase the defining technology or system from the title.

Once the draft is complete:

SLOP_CACHE=$(bash "$S/load-no-ai-slop.sh") || {
  echo "no-ai-slop unavailable; continue with the internal hard-ban sweep"
}
# Read $SLOP_CACHE/SKILL.md. Detect candidates only; revise them by hand,
# rerun the sweep, and leave no unresolved finding. Never auto-rewrite.

Medium: default LiteXML (for the site owner's blog).

LITEXML_CACHE=$(bash "$S/load-litexml.sh")
# Read $LITEXML_CACHE/SKILL.md and its references as needed.

Plain Markdown is fine when no haklex-specific tags are needed.

Do not convert the skill body into article sections. Reconstruct the blog from the narrative evidence: establish the problem, expose the consequential decisions, support claims with concrete evidence, and state the resulting view. A rejected skill candidate may still supply valuable narrative material.

[6] Publish via mxs

Follow publish-flow.md end to end — starting with mxs author (stop, wait for the user, read <file>.diff), then the post---file metadata re-attach and the post-publish metadata verification. Pass zero or more --skill-id arguments according to the accepted and successfully pushed skills. Paste the final URL back into the originating session.

Failure boundaries

Only mistakes that happen before the reference files are loaded. Publish, voice, and node rules live in those files.

Verification

• $S resolved via the search loop; bash "$S/resolve-skill-repo.sh" points at a real directory before any write.
• Intake answers recorded (or already present in the trigger) before [1].
• Draft narrator matches the recorded persona, or the deferred spine rule.
• Skill work skipped when intake said none; gates still applied when required or defer.
• Session evidence was classified among blog, reusable skill, and project documentation.
• Every skill has a capability thesis and passes all seven semantic gates.
• Every skill has one trigger family, one operational target, and one primary observable outcome.
• Frontmatter contains only name and description; the description carries all trigger conditions.
• The body contains the capability boundary, operational core, and verification without empty conditional sections.
• Scripts, references, and assets exist only when they improve deterministic reuse or progressive disclosure.
• Every accepted skill passed validation and the repository pre-commit hook; git push succeeded.
• Every successfully published skill returned a snowflake id and its ${MXS_API_URL}/api/v3/s/sk/<name> URL resolves.
• Blog body has zero mention of the skill — the skill card carries the linkage.
• Voice, node, and visual checks in writing-style.md / node-usage.md / visuals.md passed.
• Final title preserves the technical identity anchor and makes no claim broader than the evidence; slug uses stable searchable terms.
• no-ai-slop detect sweep rerun after manual edits with no unresolved finding; if the loader failed, the internal hard-ban sweep still passed and the failure was reported.
• meta.skillIds contains exactly the successfully pushed skills; it is absent or empty when no skill passed the gate.
• Publish checklist in publish-flow.md passed; final post URL pasted back into the originating session.