define-piece

Settle a writing piece's thesis, reader, scope, and outline into a confirmed brief file.

Updated Sep 17, 2026
One-click install
npx skills add https://github.com/hkw2028/toy-project --skill define-piece-hkw2028
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: define-piece
Source: https://github.com/hkw2028/toy-project/tree/main/.agents/skills/define-piece
Command: npx skills add https://github.com/hkw2028/toy-project --skill define-piece-hkw2028

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Drafting a blog post, newsletter issue, or page of copy without a settled brief leads to vague theses, unclear readers, and endless rewrites. This Skill turns a topic and rough direction into a confirmed brief at docs/briefs/<slug>/brief.md before any prose is written. ## Core Features & Use Cases - Decision-by-decision briefing: Presents a one-sentence thesis, title candidates, and a section outline for the user to correct, asking at most one consequential question at a time with a recommended answer. - Project-grounded context: Reads docs/publications/, GLOSSARY.md, docs/decisions/, and PRODUCT.md so the brief follows the publication's premise, settled terminology, and confirmed writing criteria. - Feedback capture: Records confirmed reusable writing rules and accepted examples into docs/decisions/ via the bundled feedback guidance, keeping piece-only exceptions in the brief. - Use Case: You want to write a blog post about automating smoke tests for an Expo app. The Skill proposes a thesis, title candidates, and an outline, settles the reader and three to five checkable reader questions with you, then writes the brief that drafting will follow. ## Quick Start Ask the assistant to use define-piece to settle the thesis, reader, scope, and outline for your next blog post and record the confirmed brief.

Frequently Asked Questions about define-piece

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I plan a blog post before writing it?

Use define-piece to settle the piece's thesis, target reader, reader questions, scope, and outline through a correction-based dialogue. Once every decision is confirmed, it writes a brief at docs/briefs/<slug>/brief.md that drafting follows.

What goes into a writing brief for a blog post or newsletter?

The brief records the owning publication, a one-sentence thesis, the reader and their prior knowledge, three to five checkable reader questions, scope and exclusions, source material, a section outline, execution-checked code notes, assumptions, deferred points, and remaining risks.

Can define-piece write the article body for me?

No. The brief deliberately stays free of prose; the outline carries section headings and what each section does, never paragraphs. Drafting the body is a separate step that consumes the confirmed brief.

How does define-piece handle multiple publications?

When several files exist under docs/publications/, it recommends one based on the topic with a one-line reason and waits for confirmation before settling piece-level decisions. With exactly one publication, that file governs the piece automatically.

When should I not use define-piece?

Do not use it to write body prose, to define the publication itself (that belongs to define-publication), or to shape a code work unit (that belongs to shape-idea). It only settles the brief for a single piece of writing.