Home / All Skills / Content & Media Creation / writing-shape
English (EN)简体中文 (ZH)日本語 (JA)
Content & Media Creation · mattpocock/skills

writing-shape

Writing, exploit: shape raw material into an article, paragraph by paragraph.

L2 Local · Restricted workspaceV1 Commit-PinnedWrite FileDual-pass Audit
Author mattpocockGitHub mattpocock/skills ↗Stars 257659License MIT（GitHub API spdx MIT；仓库根 LICENSE: Copyright (c) 2026 Matt Pocock）Commit 3cca18b368
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Positioned as exploit with read-only source files: treats user-provided raw material as an input pile, reading it fully to commit to a structure and mine it paragraph by paragraph; editing source files directly is explicitly forbidden.

skills/in-progress/writing-shape/SKILL.md
This is **exploit**: the exploring is done, the pile is fixed: commit to a structure and mine the pile to fill it. Do not edit the raw material file: it is read-only to this skill.
Belongs to exploit alongside writing-beats, but takes a different form: beats follows a branching journey of beats, whereas shape progresses through paragraph-level incremental formation paired with explicit formatting debate.

Main loop: read through pile → establish prerequisites with the user → provide 2–3 candidate openings (each implying a different thesis) forcing the user to pick or hybridize → grow paragraph by paragraph → persist each paragraph to disk → loop until the user stops.

skills/in-progress/writing-shape/SKILL.md
**Draft 2–3 candidate openings.** Each opening should imply a different thesis or angle for the article. Show all of them. Force the user to pick or compose a hybrid. The chosen opening defines what the rest of the article must do.
Step 4: 'ask "given this opening, what does the reader need to hear next?" Pull material from the pile to answer.'—paragraph-by-paragraph growth is driven by what the reader needs to hear next.

Format debate before committing each paragraph: the choice of paragraph, list, table, callout, quotation, or code block must be conscious and defensible, guided by clear heuristic trade-offs.

skills/in-progress/writing-shape/SKILL.md
Argue about the form the next block takes: a paragraph, a list, a table, a callout, a quote, a code block. Each format choice should be deliberate and defensible.
Example heuristic trade-offs: 'Prose vs. list. Prose carries argument; lists carry parallel items. If items aren't truly parallel, prose is better.'; 'Table vs. repeated structure. If the same shape repeats 3+ times with the same fields, a table.'

Grounding constraints share origins with beats: each block can only use already grounded concepts; if the answer to 'what does the reader need to hear next?' lacks foundation, supply the foundational block first.

skills/in-progress/writing-shape/SKILL.md
Every **concept** has to be **grounded** before a block can lean on it: the reader either walked in knowing it or met it in an earlier block. A block that reaches for an ungrounded concept loses the reader.
'When you ask "what does the reader need to hear next?", an ungrounded concept the next move needs is itself the answer: ground it first…This is the gap-naming of Pulling from the pile one level up.'

Reverse-grilling conversational feel: an inverted grilling session (shifting from 'what are you noticing?' to 'what is the piece arguing, and in what order should it be heard?'), requiring pushback, refusing weak transitions, and cutting unearned paragraphs.

skills/in-progress/writing-shape/SKILL.md
This is a grilling session inverted. In ideation, the question was "what are you actually noticing?" Here it's "what is this article actually arguing, and in what order does the reader need to hear it?" Push back. Refuse to let weak transitions slide. If a paragraph doesn't earn its place, cut it.
Accompanying cross-examination prompt list: 'What does this paragraph do for the reader that the previous one didn't?'; 'The opening promised X. We've drifted to Y. Either re-thread it or change the opening.'

Explicit gap-naming for missing material: when the pile lacks what the article needs, directly call it out for the user to fill rather than forcing prose or skipping it.

skills/in-progress/writing-shape/SKILL.md
If the pile lacks something the article needs, name the gap explicitly: "We need an example here and the pile doesn't have one. Give me one now or we cut this section."
Explicitly out of scope: no mining new fragments outside the pile, no modifying source files, no publishing, no styling/layout, and no adding unrequested frontmatter.

2Core Capabilities

01Read through source material pile in any format (fragment lists, unstructured prose, transcripts) and form an overarching assessment
02Offer 2–3 candidate openings requiring a mandatory choice (or hybridization), setting the thesis commitment for the entire piece
03Drive block-by-block accessibility via a running grounding checklist
04Format debate: explicit trade-offs across prose, list, callout, table, quote, and code block
05Explicit gap-naming to request missing material, quarrying and restructuring content from the pile
06Write and persist paragraph by paragraph to disk, re-reading from disk before each write to prevent overwrites

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Restrict working directory
For Administrators
Retain operation logs
Evidence & Triggers (File Paths & Excerpts)
  • 本地工作目录: File I/O and artifact output: user-specified independent article file: appended block by block, with in-place rewrites of specific paragraphs upon user request; source files are explicitly read-only
Audit Notes: Local file operations only: reads source files (read-only, editing explicitly prohibited) and writes to a user-specified independent article file (appends block by block + in-place paragraph edits upon user request); no scripts, no outbound network requests, no credential reading, and no delete commands. Note: write path is specified by the user ('ask once and remember the path'); the article file is kept separate from source files, preventing material pollution.

5Second-Pass Verification

  • [ok] 素材只读声明 — 'Do not edit the raw material file: it is read-only to this skill.' 原文在；Out of scope 段重复 'Editing the raw material file'。
  • [ok] 候选 opening 强制选择 + 杂交选项 — 'Force the user to pick or compose a hybrid. The chosen opening defines what the rest of the article must do.' 原文在。
  • [ok] 逐段生长循环 + 格式辩论 — 'Grow paragraph by paragraph' 步骤与 'Argue about the form the next block takes…Each format choice should be deliberate and defensible.' 均在；Format arguments 五组取舍原文在。
  • [ok] grounding 机制 — Grounding 节 + 'Keep a running list of what's grounded' 原文在；与 beats 概念一致。
  • [ok] 写前重读磁盘 / 就地改段不盲覆盖 — 'Re-read the file from disk before every write…Never overwrite blindly. If the user wants a paragraph rewritten, edit that specific paragraph in place' 原文在。
  • [ok] 文件写入范围 — 仅用户指定文章文件；素材文件只读；无删除/移动/其它路径指令。
  • [ok] 外部依赖为空 — token 扫描零命中；grilling 仅为概念引用（'grilling session inverted'），无 Skill-tool 调用指令。
  • [ok] 元数据 + beta 状态 — GitHub API MIT/257659/2026-09-04；本地 HEAD == 3cca18b；in-progress README 列为 beta。

6Verdict & Scenarios

  • Thesis commitment established upfront: mandatory selection among candidate openings prevents the piece from losing focus halfway through.
  • Explicit formatting decisions: every block's medium—prose, list, table, callout, quote, or code—must be defensible, eliminating thoughtless prose.
  • gap-naming: directly calls out missing pile material instead of forcing prose or skipping, refusing to compromise article quality over missing info.
  • Read-only source files + disk re-read before write, providing dual protection to keep user assets intact.
  • Editorial stance: pushes back, cuts unearned paragraphs, and catches drift from opening promises—acting like a senior editor rather than a typist.
    • Best for: Ideal for authors with an existing pile of raw material (fragments collection, interview transcripts, rough notes) looking to polish it into a coherent article; especially suited for those willing to debate format and argumentation paragraph by paragraph, treating the model as an editorial partner. Forms a complete pipeline when chained with writing-fragments.
    Not for: Not suited for scenarios where material is still in the exploratory phase (use explore first); not suited for users wanting a quick one-shot draft or strict outline-driven generation; not suited when material gaps cannot be filled by the user; not suited for publishing pipelines requiring platform-specific layout or frontmatter generation (explicitly out of scope).
    Install Agent-Ready
    ① Verified Mirror 2026-09-09
    Option A · Direct DownloadDownload writing-shape.tar.gz
    sha256: f8d01b68a6c6dcdf…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 3cca18b368.