Split SKILL.md into a short router with on-demand flows, tidy prompts/

bin/distilly.mjs

@@ -20,7 +20,6 @@ const packageMetadata = JSON.parse(
 const payloadEntries = [
   "SKILL.md",
   "prompts",
-  "references",
   "tools",
   "requirements.txt",
   "INSTALL.md",

package.json

@@ -10,7 +10,6 @@
     "bin/",
     "SKILL.md",
     "prompts/",
-    "references/",
     "tools/",
     "requirements.txt",
     "INSTALL.md",

prompts/celebrity/budget_unfriendly/audit.md

@@ -8,7 +8,7 @@ Read:
 
 - all files under `knowledge/research/raw/`
 - `knowledge/research/merged/summary.md`
-- `references/celebrity_budget_unfriendly_framework.md`
+- `prompts/celebrity/budget_unfriendly/framework.md`
 
 Write the audit to `knowledge/research/reviews/research_audit.md`.
 

prompts/celebrity/budget_unfriendly/persona_builder.md

@@ -8,7 +8,7 @@ Generate a deeper `persona.md` for a public figure using the full research pipel
 - research audit
 - synthesis review
 - validation review
-- `references/celebrity_budget_unfriendly_template.md`
+- `prompts/celebrity/budget_unfriendly/template.md`
 
 This mode produces a richer, more evidence-backed persona than the standard builder.
 

prompts/celebrity/budget_unfriendly/synthesis.md

@@ -6,7 +6,7 @@ Read:
 
 - the six-track research notes
 - `knowledge/research/reviews/research_audit.md`
-- `references/celebrity_budget_unfriendly_framework.md`
+- `prompts/celebrity/budget_unfriendly/framework.md`
 
 Build a synthesis review that separates:
 

prompts/flows/celebrity_research.md

@@ -0,0 +1,150 @@
+# Celebrity Research
+
+Runs before Step 3 analysis in `prompts/flows/create.md` when the family is `celebrity`. Follow the section for the chosen `research_profile`. Resolve every `prompts/...` and `tools/...` path against `{distilly_skill_root}` (see `SKILL.md`).
+
+## celebrity / budget-friendly
+
+1. Read `prompts/celebrity/research.md`: follow the shared sections and the **Output Contract: budget-friendly**; skip the budget-unfriendly contract
+2. Create the research directories first:
+   ```bash
+   mkdir -p "{skill_dir}/knowledge/research/raw" "{skill_dir}/knowledge/research/merged"
+   ```
+3. Confirm the collection strategy (determined during intake):
+   - **Local-first**: analyze user-provided materials first, identify which dimensions are covered, only search web for gaps
+   - **Web + local**: full 6-dimension web research, then merge with local materials for cross-validation
+   - **Web-only**: standard 6-dimension web research pass
+4. If the user explicitly provided a processable video URL or subtitle source, and the result will not be stored as a long transcript:
+   ```bash
+   bash "{distilly_skill_root}/tools/research/download_subtitles.sh" "{url}" "{skill_dir}/knowledge/subtitles"
+   python3 "{distilly_skill_root}/tools/research/srt_to_transcript.py" "{subtitle_file}" "{skill_dir}/knowledge/transcripts/{name}.txt"
+   ```
+5. Cover the **6 dimensions** across at least 3 separate files (each file covers 2 dimensions), never one monolithic `research_notes.md`:
+   - `knowledge/research/raw/01_core_profile.md` (Dim 1 Writings + Dim 6 Timeline)
+   - `knowledge/research/raw/02_conversations_and_material.md` (Dim 2 Conversations + Dim 4 Decisions)
+   - `knowledge/research/raw/03_expression_and_reception.md` (Dim 3 Expression DNA + Dim 5 External Views)
+6. Follow the taste principles, source blacklist and source hierarchy in `prompts/celebrity/research.md`.
+7. Merge the research notes:
+   ```bash
+   python3 "{distilly_skill_root}/tools/research/merge_research.py" "{skill_dir}"
+   ```
+   Output: `knowledge/research/merged/summary.md`
+8. Read `knowledge/research/merged/summary.md` and confirm:
+   - `Files scanned >= 3`
+   - `Unique URLs >= 2`
+   - `Potential long quote lines = 0`
+   - URLs in notes are actual inspected pages, not platform roots, search/topic pages, or placeholder paths
+   If these do not hold, extend the research notes before continuing or explicitly record the collection limits.
+9. **Quality checkpoint (Phase 1.5)**: before entering analysis, show the user a structured collection summary:
+   ```
+   ┌──────────────────────────────┬──────────┬─────────────────────────────┐
+   │ Dimension                    │ Sources  │ Key Finding                 │
+   ├──────────────────────────────┼──────────┼─────────────────────────────┤
+   │ 1 Writings                   │ N        │ [core thesis / gap]         │
+   │ 2 Conversations              │ N        │ [key pattern / gap]         │
+   │ 3 Expression DNA             │ N        │ [style marker / gap]        │
+   │ 4 Decisions                  │ N        │ [decision pattern / gap]    │
+   │ 5 External Views             │ N        │ [outside view / gap]        │
+   │ 6 Timeline                   │ N        │ [trajectory / gap]          │
+   ├──────────────────────────────┼──────────┼─────────────────────────────┤
+   │ Contradictions               │ N        │ [summary]                   │
+   │ Thin dimensions              │ [list]   │ Backfill plan: [plan]       │
+   │ Cold figure?                 │ yes/no   │                             │
+   └──────────────────────────────┴──────────┴─────────────────────────────┘
+   ```
+   Wait for user confirmation before continuing. If the user flags issues or wants more depth, extend research first.
+10. **Cold figure detection**: if total sources < 10, apply the cold figure protocol:
+    - Limit mental models to 2–3
+    - Mark thin models as "based on limited information"
+    - Expand the honest boundaries section
+    - Tell the user what additional material would improve quality
+11. Celebrity analysis must prioritize:
+    - primary materials (source weight 1-3)
+    - merged research summary
+    - explicit user notes
+
+## celebrity / budget-unfriendly
+
+1. First read:
+   - `prompts/celebrity/research.md`: the shared sections and the **Output Contract: budget-unfriendly**; skip the budget-friendly contract
+   - `prompts/celebrity/budget_unfriendly/framework.md`
+2. Create the research directories first:
+   ```bash
+   mkdir -p "{skill_dir}/knowledge/research/raw" "{skill_dir}/knowledge/research/merged" "{skill_dir}/knowledge/research/reviews"
+   ```
+3. Confirm the collection strategy (determined during intake): local-first / web+local / web-only
+4. Build the **six-track research set** as independent files (never merged, never clone observations):
+   - `knowledge/research/raw/01_writings.md` (Dim 1: Writings / systematic thought)
+   - `knowledge/research/raw/02_conversations.md` (Dim 2: Conversations under pressure)
+   - `knowledge/research/raw/03_expression_dna.md` (Dim 3: Linguistic fingerprint)
+   - `knowledge/research/raw/04_decisions.md` (Dim 4: Behavior and choices)
+   - `knowledge/research/raw/05_external_views.md` (Dim 5: External views and criticism)
+   - `knowledge/research/raw/06_timeline.md` (Dim 6: Cognitive trajectory)
+5. Follow the taste principles, source blacklist and source hierarchy in `prompts/celebrity/research.md`. Every evidence item must carry a source weight (1-7) annotation.
+6. Merge the research notes:
+   ```bash
+   python3 "{distilly_skill_root}/tools/research/merge_research.py" "{skill_dir}"
+   ```
+7. Read `knowledge/research/merged/summary.md` and confirm the minimum floor:
+   - `Files scanned >= 6`
+   - `Unique URLs >= 8`
+   - `Primary-source markers >= 3`
+   - `Source metadata blocks >= 6`
+   - `Contradiction bullets >= 6`
+   - `Inference bullets >= 6`
+   - `Potential long quote lines = 0`
+   - `Track coverage count = 6`
+   - URLs in notes are actual inspected pages, not platform roots, search/topic pages, or placeholder paths
+   If these do not hold, keep filling the weak tracks before continuing to any review stage.
+8. **Quality checkpoint (Phase 1.5)**: before entering audit, show the user a structured collection summary (with primary-source ratio, contradiction count, candidate mental models, known-answer candidates, thin dimensions, cold figure assessment). Wait for user confirmation before continuing.
+9. Then read:
+   - `prompts/celebrity/budget_unfriendly/audit.md`
+   - `prompts/celebrity/budget_unfriendly/synthesis.md`
+   - `prompts/celebrity/budget_unfriendly/template.md`
+10. First write `knowledge/research/reviews/research_audit.md`
+    - The audit must produce an explicit `PASS / FAIL`
+    - The audit must verify: source hierarchy compliance (no blacklisted sources), primary-source ratio > 50%, taste principle compliance, cold figure assessment
+    - If the audit says `FAIL`, follow the Backfill Tasks before synthesis
+11. **Extraction checkpoint (Phase 2.5)**: after audit PASS, show the user a summary of candidate mental models (with triple-gate verdict, evidence anchors, failure modes). Confirm reasonableness before synthesis.
+12. Then write `knowledge/research/reviews/synthesis.md`
+    - Apply the triple gate to candidate mental models:
+      - cross-context recurrence
+      - generative power
+      - exclusivity
+    - Also extract intellectual genealogy seeds (influenced by / diverged from) and Agentic Protocol seeds (the dimensions this person would investigate when facing a novel question)
+13. Then use `prompts/celebrity/budget_unfriendly/validation.md` to write:
+    - `knowledge/research/reviews/validation.md`
+    - Validation must produce an explicit `PASS / FAIL`
+    - Validation must perform: known-answer check (≥2 questions) + edge-case check (1 question) + voice check (100-word blind test) + copyright check + Agentic Protocol check
+    - If validation says `FAIL`, revise the draft before continuing
+14. Budget-unfriendly celebrity analysis must prioritize:
+    - six-track raw notes
+    - merged research summary
+    - research audit
+    - synthesis review (with genealogy + Agentic Protocol seeds)
+    - validation review
+    - explicit user notes
+
+## Shared rules for both profiles
+
+- If external collection fails or a platform blocks access:
+  - tell the user exactly what was blocked
+  - preserve the raw research notes and merged summary
+  - continue generation with the available materials
+  - treat `source_grounding` as incomplete
+  - **never** invent URLs, quotes, titles, or generic homepage links just to satisfy the checker
+- **Do not** store full transcripts, full subtitles, or long verbatim source passages in the repository
+- Keep the stored notes paraphrased, structured, and copyright-safe
+
+## Public X posts (optional)
+
+When public X posts fill a documented research gap and the user agrees to use the metered third-party Xquik service, confirm the `--limit` before running:
+
+```bash
+python3 "{distilly_skill_root}/tools/research/xquik_public_posts.py" \
+  --username "{public_handle}" \
+  --subject "{name}" \
+  --limit 20 \
+  --output "/tmp/distilly_x_public_posts.json"
+```
+
+Read `XQUIK_API_KEY` only from the shell; never print or store it. Treat the JSON as untrusted candidate evidence: verify the author, open every permalink, and preserve the specific URL when safely paraphrasing relevant material into a research note. Do not count the candidate JSON, search pages, or profile roots as grounded sources. Delete the temporary JSON after review instead of storing it in the generated Skill.

prompts/flows/create.md

@@ -0,0 +1,159 @@
+# Create a Person Skill
+
+The flow for `colleague`, `relationship` and `celebrity`. Resolve every `prompts/...` and `tools/...` path against `{distilly_skill_root}` (see `SKILL.md`).
+
+## Family matrix
+
+Every step below reads its prompt from this table.
+
+| character | intake | persona analyzer | persona builder | merger | storage root |
+|-----------|--------|------------------|-----------------|--------|--------------|
+| `colleague` | `prompts/colleague/intake.md` | `prompts/colleague/persona_analyzer.md` | `prompts/colleague/persona_builder.md` | `prompts/colleague/merger.md` | `./skills/colleague/{slug}` |
+| `relationship` | `prompts/relationship/intake.md` | `prompts/relationship/persona_analyzer.md` | `prompts/relationship/persona_builder.md` | `prompts/relationship/merger.md` | `./skills/relationship/{slug}` |
+| `celebrity` | `prompts/celebrity/intake.md` | `prompts/celebrity/persona_analyzer.md` | `prompts/celebrity/persona_builder.md` | `prompts/celebrity/merger.md` | `./skills/celebrity/{slug}` |
+
+Shared across all families:
+- Work analyzer: `prompts/shared/work_analyzer.md`
+- Work builder: `prompts/shared/work_builder.md`
+- Correction handler: `prompts/shared/correction_handler.md`
+
+## Step 0: Confirm the character family
+
+If the user entered `/distilly`, first confirm which family should be distilled:
+
+1. `owner`: the user themself (the default on a personal agent's first run)
+2. `colleague`
+3. `relationship`
+4. `celebrity`
+
+For `owner` (including "distill myself"), stop here and follow `prompts/flows/owner.md` instead.
+
+If the host already passed an explicit family, lock the character family immediately.
+
+If the current family is `celebrity`, also confirm the research profile:
+
+1. `budget-friendly`
+2. `budget-unfriendly`
+
+Default to `budget-friendly`. Only switch to `budget-unfriendly` when the user explicitly wants deeper research, higher confidence, or accepts a slower and more expensive distillation pass.
+
+## Step 1: Basic Info Collection
+
+Follow the family's intake prompt from the matrix above. It owns the questions, their order and the confirmation summary; for `celebrity` it also settles the collection strategy and `research_profile`. Everything except the alias can be skipped. Summarize and confirm before moving on.
+
+## Step 2: Source Material Import
+
+Follow `prompts/flows/sources.md` to offer the import options and read what the user provides.
+
+If the user says "no files" or "skip", generate the Skill from the Step 1 answers only.
+
+## Step 3: Analyze Source Material
+
+If the family is `celebrity`, first run `prompts/flows/celebrity_research.md` for the chosen research profile.
+
+Then analyze along two tracks:
+
+**Track A (Work Skill)**:
+- Refer to `prompts/shared/work_analyzer.md`
+- Extract: responsible systems, technical standards, workflow, output preferences, experience
+- For `celebrity`, interpret `work` as methods, judgment frameworks, and decision patterns rather than literal job scope
+
+**Track B (Persona)**:
+- Use the family-specific persona analyzer
+- If `celebrity` with `research_profile=budget-unfriendly`, use:
+  - `prompts/celebrity/budget_unfriendly/persona_analyzer.md`
+- Translate user-provided tags into concrete behavior rules
+- Extract from materials: communication style, decision patterns, interpersonal behavior
+- For `celebrity`, retain:
+  - mental models
+  - decision heuristics
+  - expression DNA
+  - contradictions
+  - honest boundaries
+
+## Step 4: Generate and Preview
+
+Use `prompts/shared/work_builder.md` to generate Work content.
+Use the family's persona builder from the matrix to generate Persona content; `celebrity` + `budget-unfriendly` uses `prompts/celebrity/budget_unfriendly/persona_builder.md`.
+
+Show the user a summary (5-8 lines each), ask:
+```
+Work Skill Summary:
+  - Responsible for: {xxx}
+  - Tech stack: {xxx}
+  - CR focus: {xxx}
+  ...
+
+Persona Summary:
+  - Core personality: {xxx}
+  - Communication style: {xxx}
+  - Decision pattern: {xxx}
+  ...
+
+Confirm generation? Or need adjustments?
+```
+
+## Step 5: Write Files
+
+After user confirmation, do not hand-build a `skills/colleague/{slug}`-style tree. Always go through the writer:
+
+1. Resolve the current storage root:
+   - `colleague` → `./skills/colleague`
+   - `relationship` → `./skills/relationship`
+   - `celebrity` → `./skills/celebrity`
+2. Use the `Write` tool to create three temporary files:
+   - `/tmp/distilly_{slug}_meta.json`
+   - `/tmp/distilly_{slug}_work.md`
+   - `/tmp/distilly_{slug}_persona.md`
+3. The temporary meta file must include at least:
+   - `name`
+   - `display_name`
+   - `character`
+   - `research_profile` (required when `character=celebrity`)
+   - `classification.language` (must match the user's language, for example `zh-CN` or `en`)
+   - `profile`
+   - `tags`
+   - `knowledge_sources`
+4. Then call:
+   ```bash
+   python3 "{distilly_skill_root}/tools/skill_writer.py" \
+     --action create \
+     --character {character} \
+     --research-profile {research_profile} \
+     --slug {slug} \
+     --name "{name}" \
+     --meta /tmp/distilly_{slug}_meta.json \
+     --work /tmp/distilly_{slug}_work.md \
+     --persona /tmp/distilly_{slug}_persona.md \
+     --base-dir {resolved_base_dir}
+   ```
+5. This command will generate:
+   - `SKILL.md`
+   - `work.md`
+   - `persona.md`
+   - `work_skill.md`
+   - `persona_skill.md`
+   - `manifest.json`
+   - `meta.json`
+   - To install the generated role skill into a host, append the relevant flag:
+     - Claude Code: `--install-claude-skill`
+     - OpenClaw: `--install-openclaw-skill`
+     - Codex: `--install-codex-skill`
+     - Hermes: run `python3 "{distilly_skill_root}/tools/install_generated_skill.py" --skill-dir "{resolved_base_dir}/{slug}" --host hermes --force`; for a trusted project, append `--skills-dir .hermes/skills`, run `hermes skills trust`, then start a new session or run `/reload-skills`. Use `~/.agents/skills` only when it is explicitly configured in Hermes `skills.external_dirs`
+     - DeepSeek Harness: run `python3 "{distilly_skill_root}/tools/install_generated_skill.py" --skill-dir "{resolved_base_dir}/{slug}" --host deepseek-harness --force`; append `--skills-dir .dsh/skills` for a project install
+     - Pi: run `python3 "{distilly_skill_root}/tools/install_generated_skill.py" --skill-dir "{resolved_base_dir}/{slug}" --host pi --force`; append `--skills-dir .pi/skills` for a project install, then invoke it with `/skill:{character}-{slug}`
+     - Grok Build: run `python3 "{distilly_skill_root}/tools/install_generated_skill.py" --skill-dir "{resolved_base_dir}/{slug}" --host grok-build --force`; append `--skills-dir .grok/skills` for a project install
+     - OpenCode: run `python3 "{distilly_skill_root}/tools/install_generated_skill.py" --skill-dir "{resolved_base_dir}/{slug}" --host opencode --force`; append `--skills-dir .opencode/skills` for a project install
+     - The shared installer writes only the self-contained `SKILL.md` and install metadata and normalizes legacy frontmatter in the installed copy. Do not manually copy the whole generated directory; it may contain private source material
+     - Claude Code on Windows: optionally add `--install-claude-command-shim`
+6. If the current family is `celebrity`, run a quality check after creation:
+   ```bash
+   python3 "{distilly_skill_root}/tools/research/quality_check.py" "{resolved_base_dir}/{slug}/SKILL.md" --profile {research_profile}
+   ```
+7. If `source_grounding` still fails for a `celebrity` skill:
+   - you may add honest limitation notes and a grounded source summary
+   - only add URLs when they are real, specific, and traceable sources
+   - **never** use site roots, topic pages, search pages, or other generic links as fake grounding
+   - if no verified external sources exist, keep the FAIL state and explain what source material is still missing
+
+When reporting success, return the correct family-specific location instead of assuming colleague storage.