coracle-rust/.agents/skills/write-chapter/SKILL.md

name, description

name	description
write-chapter	Write a book chapter from its plan with tangled Rust code

Write Chapter

You are writing a chapter of a literate programming book about nostr. The chapter name is provided as an argument: $ARGUMENTS.

Step 1: Read the Plan

Read the chapter plan at ./book/plan/$ARGUMENTS.md. This contains the outline, API design, code organization, dependencies, and narrative notes developed with the user.

If the plan file does not exist, tell the user to run /plan-chapter $ARGUMENTS first and stop.

Also read:

• ./book/SUMMARY.md to understand the book structure and where this chapter fits
• Any existing chapters referenced in the plan to ensure continuity
• The existing code in any crate src/ directories that this chapter will extend (these are generated by tangle, but reading them shows the current state)

Step 2: Write the Chapter

Create or update the chapter markdown file in ./book/. Follow these conventions:

• Literate style: The prose is the primary artifact. Code blocks are woven into the narrative, not dumped in bulk.
• Code blocks that should be tangled use the annotation format:

  ```rust {file=crate-name/src/path.rs}
  ```
  

• Multiple code blocks can target the same file — they are concatenated in document order.
• Code blocks without {file=...} are illustrative (examples, JSON, shell commands).
• Explain why before showing what. A reader should understand the motivation before seeing the implementation.
• Keep code blocks focused — one concept per block where possible.
• Ensure all use statements and module declarations are included in tangled blocks.
• Update ./book/SUMMARY.md if adding a new chapter.
• Update any Cargo.toml files if new dependencies are needed.

Step 3: Validate

Run just all to verify that:

1. The tangle step extracts valid Rust source files
2. The Rust code compiles successfully
3. The mdBook build succeeds

If the build fails, read the error output, fix the issue in the chapter markdown (not in generated src/ files), and run just all again. Repeat until the build passes.

Step 4: Report

Tell the user the chapter is written and building. Summarize:

• What sections were written
• What types/functions were implemented
• Any deviations from the plan and why
• Any open items or things to revisit