diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..87eb031
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,129 @@
+# Agent Instructions
+
+These instructions apply to the whole repository. Keep this file focused on
+project knowledge: what `embed-code-go` is, where the major responsibilities
+live, and which local skill owns the detailed working rules.
+
+## Operating Policy
+
+- Read this file and the relevant skill before changing the workspace.
+- Ask clarifying questions before implementation, review, or documentation work
+  when scope, acceptance criteria, or constraints are not explicit.
+- Never create commits, push, tag, merge, rebase, cherry-pick, or rewrite Git
+  history in this repository.
+- Preserve unrelated local changes. Treat them as user work.
+
+## Skills
+
+- `skills/go-engineer/SKILL.md`: Go implementation, debugging, refactoring,
+  parser and embedding behavior, error handling, formatting, vetting, and
+  build verification.
+- `skills/go-tester/SKILL.md`: Go test authoring and test review, including
+  Ginkgo/Gomega style, fixtures, package-level test ownership, and test command
+  selection.
+- `skills/writer/SKILL.md`: documentation authoring and editing for
+  `README.md`, `EMBEDDING.md`, `AGENTS.md`, skills, Markdown fixtures, and Go
+  doc comments.
+- `skills/review-docs/SKILL.md`: documentation review for Go doc comments,
+  Markdown, `README.md`, `EMBEDDING.md`, skills, and this file.
+
+Apply multiple skills when a task crosses these boundaries.
+
+## Project Overview
+
+`embed-code-go` is a Go 1.22.1 command-line application. It scans Markdown and
+HTML documents for `embed-code` instructions, resolves source fragments,
+renders them inside code fences, and checks whether existing snippets are
+up-to-date.
+
+The architecture follows a one-way flow from process orchestration to document
+processing and source resolution. Keep syntax recognition, source extraction,
+filesystem handling, and CLI concerns within their owning packages. Do not
+collapse them into a broad utility layer or introduce circular dependencies.
+
+## Processing Flow
+
+The normal execution path is:
+
+1. `main.go` reads arguments, configures logging, validates input, and dispatches
+   `embed` or `check` mode.
+2. `cli/` reads flags or YAML and produces one or more normalized
+   `configuration.Configuration` values.
+3. `embedding.EmbedAll` or `embedding.CheckUpToDate` selects documentation files
+   using include and exclude patterns.
+4. An `embedding.Processor` processes one document at a time.
+5. `embedding/parsing/` walks the document through explicit states, records each
+   instruction and its code fence, and preserves unrelated document content.
+6. A parsed `Instruction` resolves source content through `fragmentation/`,
+   optional line patterns, indentation normalization, and comment filtering.
+7. Embed mode writes changed documents. Check mode compares generated content
+   with existing content and must not modify documentation.
+
+When behavior changes, trace the complete path instead of patching only the
+first function that exposes the symptom.
+
+## Package Map
+
+- `main.go`: executable entry point, mode dispatch, aggregate errors, and final
+  user-facing output.
+- `cli/`: flag parsing, YAML loading, validation, and conversion to runtime
+  configuration.
+- `configuration/`: defaults and normalized settings used by processing code.
+- `embedding/`: document discovery, per-document processing, embedding writes,
+  and up-to-date checks.
+- `embedding/parsing/`: state-machine parser for instructions, ordinary
+  Markdown fences, embedding fences, and rendered-content comparison.
+- `embedding/commentfilter/`: language-aware filtering for comment-retention
+  modes.
+- `fragmentation/`: whole-file, named-fragment, and line-pattern extraction;
+  source lookup; partition assembly; encoding checks; and caches.
+- `files/`: filesystem validation and file helpers.
+- `indent/`: shared indentation measurement and removal.
+- `logging/`: `slog` handler, clickable file references, panic reporting, and
+  terminal formatting support.
+- `type/`: YAML-compatible string and named-path list types. Preserve this
+  existing package name even though it is unusual.
+- `test/resources/`: parser, embedding, configuration, and source-code fixtures.
+
+## Parser And Embedding Rules
+
+- The parser is state-machine based. When changing parsing behavior, inspect
+  `embedding/parsing/constants.go`, `state.go`, `context.go`, and the relevant
+  state implementation together.
+- Preserve the supported instruction forms:
+  - `<embed-code file="..."/>`;
+  - `<embed-code file="..."></embed-code>`;
+  - multiline instructions represented by existing fixtures.
+- Instruction-looking text inside an unrelated Markdown code fence is ordinary
+  content, not an active embedding instruction.
+- Preserve the opening fence's marker length and indentation when recognizing
+  the closing fence and rendering source lines.
+- Malformed-instruction errors should point to the instruction start line, not
+  EOF or a later fence line.
+- Prefer concrete parse reasons: missing tag end, missing closing tag, invalid
+  XML, missing code fence, or unclosed code fence.
+- Do not scan arbitrary later document content to guess where an invalid
+  instruction ends.
+- Embed mode may rewrite only documents whose generated content changed.
+- Check mode is read-only and should identify every stale document it can safely
+  inspect.
+
+## Documentation Ownership
+
+- `AGENTS.md`: project map, processing flow, package ownership, skill routing,
+  and repository-level invariants.
+- `README.md`: user-facing overview, installation, configuration, modes, flags,
+  and normal operation.
+- `EMBEDDING.md`: embedding syntax, source markers, patterns, fences,
+  separators, comment modes, and examples.
+- `skills/`: operational rules for agents. Keep language-specific, testing, and
+  documentation authoring/review policy in the relevant skill rather than
+  duplicating it here.
+
+## Repository Hygiene
+
+- Do not revert unrelated user changes.
+- Do not edit generated binaries under `bin/` unless explicitly requested.
+- Do not add temporary repo files, local binaries, IDE metadata, coverage
+  output, or build artifacts to the intended change set.
+- Keep changes narrowly scoped and make unrelated cleanup a separate task.
diff --git a/skills/go-engineer/SKILL.md b/skills/go-engineer/SKILL.md
new file mode 100644
index 0000000..dbc3423
--- /dev/null
+++ b/skills/go-engineer/SKILL.md
@@ -0,0 +1,146 @@
+---
+name: go-engineer
+description: >
+  Encodes the embed-code-go Go implementation policy and recurring pitfalls.
+  Use whenever writing, modifying, refactoring, debugging, or reviewing Go code
+  in this repository, especially CLI/config parsing, parser state transitions,
+  embedding behavior, fragmentation, filesystem handling, error reporting,
+  package APIs, formatting, vetting, and build verification.
+---
+
+# Go - policy & pitfalls
+
+Baseline Go knowledge is assumed. This skill does not teach the language; it
+encodes the project policy, package boundaries, and traps that recur in `embed-code-go` work.
+
+## When to Use
+
+Use `go-engineer` for implementation work in Go:
+
+- Writing or changing `.go` files.
+- Debugging `embed` or `check` behavior.
+- Refactoring package APIs or shared helpers.
+- Reviewing Go code for correctness and maintainability.
+
+This skill is the baseline for production Go and helper code. Test-writing
+conventions live in `skills/go-tester/SKILL.md`; documentation review lives in
+`skills/review-docs/SKILL.md`.
+
+## Fast Path for Agents
+
+1. Read `AGENTS.md` and the relevant implementation files in full.
+2. Ask clarifying questions before editing if the requested outcome, scope,
+   compatibility constraints, or verification target is not explicit.
+3. Apply the MUST / MUST NOT rules while editing.
+4. Defer test structure and fixtures to `go-tester` when adding or reviewing
+   tests.
+5. Verify with the narrowest relevant Go test first, then the repository-level
+   checks listed below.
+6. Do not commit, push, tag, merge, rebase, cherry-pick, or rewrite Git history.
+
+## Setup Check
+
+Run this before non-trivial Go changes or when the package baseline is unclear:
+
+1. **Go version** - target the version in `go.mod`.
+2. **Package owner** - identify whether the behavior belongs in `cli/`,
+   `configuration/`, `embedding/`, `embedding/parsing/`, `fragmentation/`, or a
+   support package.
+3. **Test owner** - identify the package test suite and fixtures that already
+   cover the behavior.
+4. **Commands** - plan `gofmt`, focused `go test`, `go vet ./...`, full
+   `go test ./...`, and `go build -trimpath main.go` when integration or CLI
+   behavior changes.
+
+## MUST DO
+
+- **Preserve package ownership.** Keep process orchestration in `main.go`,
+  argument and YAML handling in `cli/`, normalized defaults in
+  `configuration/`, document orchestration in `embedding/`, syntax recognition
+  in `embedding/parsing/`, and source extraction in `fragmentation/`.
+- **Trace the full flow.** For behavior changes, walk
+  `main` -> `cli`/`configuration` -> `embedding` -> `embedding/parsing` and
+  `fragmentation` -> write or compare.
+- **Keep functions small and explicit.** Prefer direct code over broad helpers
+  unless an abstraction removes real duplication or clarifies a shared contract.
+- **Document every function and method.** Add concise doc comments to new or
+  changed functions, including unexported ones. Exported comments start with
+  the declaration name.
+- **Return actionable errors.** Add file, pattern, instruction, or operation
+  context where that context becomes known.
+- **Aggregate independent failures with `errors.Join`.** Continue processing
+  only when doing so produces a more complete and still safe result.
+- **Preserve deterministic behavior.** Document order, fragment order,
+  separators, writes, and reported stale files must stay stable.
+- **Use OS-aware paths.** Preserve cross-platform behavior for separators,
+  Windows drive paths, and file URLs.
+- **Format changed Go files with `gofmt`.**
+
+## MUST NOT DO
+
+- **No new panics in library packages.** Return errors; leave process exit and
+  panic recovery at the executable boundary.
+- **No broad utility dumping ground.** Do not move parser, filesystem,
+  fragmentation, and CLI behavior into a catch-all helper package.
+- **No single-use interface by default.** Introduce an interface only at a real
+  consumer, ownership, or test boundary.
+- **No speculative concurrency.** This CLI is document and filesystem heavy;
+  add concurrency only for a measured problem with deterministic aggregation
+  and write safety.
+- **No log-and-return in lower layers.** Return the error; log at the CLI
+  boundary or at intentional progress/warning points.
+- **No message-string error contracts.** Prefer typed errors, sentinels, or
+  `errors.Is` / `errors.As`.
+- **No dependency updates unless the confirmed task requires them.**
+- **No commits or history-writing.**
+
+## Project Hotspots
+
+### Parser State Machine
+
+- Read `embedding/parsing/constants.go`, `state.go`, `context.go`, the affected
+  state, and `embedding/processor.go` together.
+- Preserve self-closing, paired, and multiline instruction forms.
+- Keep ordinary Markdown fences separate from embedding fences.
+- Report malformed instructions at their start line with a concrete reason.
+- Do not consume unrelated later content to recover from invalid XML.
+
+### Embedding And Check Modes
+
+- Embed mode may rewrite only documents whose generated content changed.
+- Check mode is read-only and reports stale documents.
+- Shared processing changes should preserve both modes.
+
+### Fragmentation
+
+- Preserve whole-file, named-fragment, exact-pattern, and range-pattern extraction.
+- Keep partition ordering, separator rendering, indentation normalization, and
+  comment filtering stable.
+- Keep source-root names and lookup errors actionable.
+
+## Verification
+
+Run the narrowest relevant checks first, then broaden:
+
+1. `gofmt -w <changed-go-files>`
+2. `go test ./<affected-package>`
+3. `go vet ./...`
+4. `go test ./...`
+5. `go build -trimpath main.go` when CLI, configuration, embedding, or package
+   integration behavior changed
+
+For user-visible CLI behavior, run a focused `go run ./main.go ...` scenario
+against existing fixtures when practical.
+
+## Output Format
+
+When producing code:
+
+1. A short plan after clarification.
+2. The code changes.
+3. A verification checklist with command results.
+4. A note about any remaining risk or unrun check.
+
+When reviewing code: call out MUST-DO / MUST-NOT violations explicitly and
+suggest the minimal fix. End with a one-line verdict: `APPROVE`,
+`APPROVE WITH CHANGES`, or `REQUEST CHANGES`.
diff --git a/skills/go-engineer/agents/openai.yaml b/skills/go-engineer/agents/openai.yaml
new file mode 100644
index 0000000..6da3a8c
--- /dev/null
+++ b/skills/go-engineer/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Go Engineer"
+  short_description: "Implement Go changes for embed-code-go"
+  default_prompt: "Use $go-engineer to implement a scoped Go change in embed-code-go."
diff --git a/skills/go-tester/SKILL.md b/skills/go-tester/SKILL.md
new file mode 100644
index 0000000..3561cd7
--- /dev/null
+++ b/skills/go-tester/SKILL.md
@@ -0,0 +1,137 @@
+---
+name: go-tester
+description: >
+  The embed-code-go authority on writing and reviewing Go tests. Use when
+  adding, restructuring, or reviewing tests for Go production code, parser
+  behavior, embedding flows, fragmentation, CLI/config validation, fixtures,
+  malformed inputs, regression coverage, focused go test commands, or full
+  suite verification. go-engineer remains the baseline for Go inside test
+  helper code.
+---
+
+# Go tester
+
+This skill is the single source of truth for how tests are written in
+`embed-code-go`. It does not decide what behavior to change; it decides how to
+cover the known behavior once the cases are identified.
+
+Two companions own neighboring concerns:
+
+- `skills/go-engineer/SKILL.md` - Go implementation policy and production code correctness.
+- `skills/review-docs/SKILL.md` - documentation review for test fixtures and
+  Markdown docs when prose changes are part of the task.
+
+## Core Policy
+
+1. **Follow existing Ginkgo/Gomega style.** Packages use `Describe` and `It`
+   suites with Gomega expectations. Match the surrounding package before adding
+   a new style.
+2. **Test behavior at the owning package.** Put the focused regression test near
+   the package that owns the bug or feature.
+3. **Use fixtures for document behavior.** Parser and embedding changes should
+   add or update files under `test/resources/` when source or document shape is
+   part of the contract.
+4. **Cover both success and failure when parser behavior changes.** Malformed
+   instruction tests are as important as successful embedding tests.
+5. **Keep tests deterministic and portable.** Avoid machine-specific absolute
+   paths, map iteration order, hidden local files, and OS-specific separators
+   unless the code intentionally emits them.
+6. **Do not commit or rewrite history.**
+
+## Workflow
+
+1. **Read first.** Read the code under test, its package tests, and relevant
+   fixtures in full.
+2. **Identify the owning suite.** Prefer extending an existing `Describe` block
+   over creating a parallel test structure.
+3. **Choose the level.** Use package-level unit tests for pure helpers, parser
+   tests for state-machine behavior, and embedding tests for end-to-end
+   document rewrites or stale checks.
+4. **Add the minimal fixture.** Create or update only the source and document
+   fixture needed to express the behavior.
+5. **Assert behavior, not implementation trivia.** Prefer outputs, changed-file
+   lists, typed errors, and line numbers over private state.
+6. **Run the narrowest test first.** Broaden only after the focused test passes.
+
+## Naming And Structure
+
+- Keep test files beside the package they test, using the existing `_test.go`
+  naming pattern.
+- Match the package's current package name. Do not switch between internal and
+  external test packages without a reason.
+- Use `Describe` for the unit or component under test and `It` for the behavior sentence.
+- Keep setup close to the test unless the package already has a clear helper pattern.
+- Use `BeforeEach` only when it reduces duplication without hiding essential state.
+- Avoid broad helper functions that make the fixture harder to read.
+
+## Assertions
+
+- Use Gomega matchers already used by the package.
+- Prefer exact content assertions for rendered snippets when formatting is the contract.
+- Prefer typed error checks with `errors.As` when the code exposes a typed error.
+- Verify line numbers for malformed instructions, especially when the bug is an
+  EOF or later-fence misreport.
+- Avoid matching full error strings unless the user-facing message itself is
+  the behavior under test.
+
+## Fixture Guidance
+
+### Documentation Fixtures
+
+- Put documentation files under `test/resources/docs/`.
+- Keep one behavior per fixture unless a multi-case document is already the
+  package convention.
+- Name malformed fixtures after the malformed condition, not the expected implementation fix.
+- Preserve indentation and code-fence marker details when those are part of the behavior.
+
+### Source Fixtures
+
+- Put source files under the existing language folder in `test/resources/code/`.
+- Add the smallest source file or fragment marker needed for the behavior.
+- Reuse existing Java, Kotlin, plain-text, or literal-pattern fixtures when
+  doing so keeps the test clearer.
+
+### Prepared Fragments
+
+- Use `test/resources/prepared-fragments/` only for behavior that already relies
+  on prepared expected content.
+- Keep expected files stable and easy to diff.
+
+## Verification
+
+Use the smallest useful command while iterating:
+
+- Parser changes: `go test ./embedding/parsing`
+- Embedding behavior: `go test ./embedding`
+- Fragment extraction: `go test ./fragmentation`
+- CLI/config behavior: `go test ./cli`
+- Shared or uncertain behavior: `go test ./...`
+
+After Go test code changes, run:
+
+1. `gofmt -w <changed-go-files>`
+2. the focused package test
+3. `go test ./...`
+
+Run `go vet ./...` when the test change also changes helper code, exported
+test support, or production code.
+
+## Repo Notes
+
+- Tests use the repository fixtures heavily; prefer a focused fixture over a
+  large inline string when document shape matters.
+- Do not rely on local absolute paths except where the code intentionally emits
+  a `file://` reference.
+- If the implementation change is still unclear, return to `go-engineer`
+  before writing tests.
+
+## Output Format
+
+When writing tests:
+
+1. State the behavior being covered.
+2. List fixtures added or changed.
+3. Report focused and full test commands run.
+
+When reviewing tests: group findings as `Must fix`, `Should fix`, and `Nits`.
+End with `APPROVE`, `APPROVE WITH CHANGES`, or `REQUEST CHANGES`.
diff --git a/skills/go-tester/agents/openai.yaml b/skills/go-tester/agents/openai.yaml
new file mode 100644
index 0000000..9785b66
--- /dev/null
+++ b/skills/go-tester/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Go Tester"
+  short_description: "Write embed-code-go Go tests"
+  default_prompt: "Use $go-tester to add or review tests in embed-code-go."
diff --git a/skills/review-docs/SKILL.md b/skills/review-docs/SKILL.md
new file mode 100644
index 0000000..a6fe13d
--- /dev/null
+++ b/skills/review-docs/SKILL.md
@@ -0,0 +1,109 @@
+---
+name: review-docs
+description: >
+  Reviews documentation changes in embed-code-go: Go doc comments, inline
+  comments, README.md, EMBEDDING.md, AGENTS.md, skills, Markdown fixtures, and
+  user-facing examples. Use when a diff touches prose, documentation comments,
+  embedding syntax docs, command examples, architecture/package maps, or agent
+  instructions. Read-only; does not run builds unless explicitly asked.
+---
+
+# Review documentation (repo-specific)
+
+You are the documentation reviewer for `embed-code-go`. Focus strictly on
+documentation quality: Go doc comments, inline comments, Markdown, examples,
+and repository guidance. Do not duplicate `writer` for authoring strategy,
+`go-engineer` for implementation correctness, or `go-tester` for test design.
+
+## Review Procedure
+
+1. **Scope the diff.** Review changed documentation files and changed comments
+   inside Go sources. Do not review the full repository unless asked.
+2. **Read each affected file fully.** Prose quality, heading hierarchy, command
+   accuracy, and identifier references require context beyond the diff hunk.
+3. **Verify claims against source.** When documentation mentions flags,
+   attributes, parser behavior, package ownership, or command output, confirm it
+   against the relevant code or tests.
+4. **Stay in scope.** If you spot a code or test issue, mention it briefly as a
+   handoff item for `go-engineer` or `go-tester` instead of expanding the docs review.
+
+## Checks
+
+### A. Go Doc Comments
+
+- **Every new or changed function and method has a doc comment.** This project
+  documents unexported functions too.
+- **Exported comments start with the exact declaration name.** Follow standard
+  Go doc style for exported types, constants, variables, functions, and methods.
+- **Unexported comments explain intent.** Starting with the function name is
+  preferred when it reads naturally.
+- **Comments describe behavior, not signatures.** Avoid prose that only
+  restates parameters, return values, or obvious assignments.
+- **Mention important effects.** Document filesystem writes, state transitions,
+  returned errors, panic behavior, and non-obvious parser constraints.
+- **Inline comments in production code are rare.** They should explain why a
+  constraint exists, not narrate what the next line does.
+- **Paths and identifiers are exact.** Render file paths, package paths, command
+  names, flags, and code identifiers in backticks.
+
+### B. Markdown Docs
+
+- **Heading hierarchy is valid.** Use one top-level `#`; do not skip heading levels.
+- **Commands are fenced.** Use fenced code blocks for shell commands and file
+  examples. Avoid indented command blocks.
+- **Examples are current.** Verify documented flags, modes, config keys,
+  instruction attributes, and default values against code.
+- **Links resolve.** Check local relative links and referenced paths. External
+  inline links are acceptable when the surrounding file already uses them.
+- **Terminology is consistent.** Use one term for the same concept within a
+  change set: embedding instruction, code fence, fragment, source root, docs
+  root, check mode, embed mode.
+- **No orphans.** A paragraph, list item, or table cell must not end with a
+  final line containing only one word. Flag it and propose a reflow or rewrite.
+- **Project docs keep their ownership.** `README.md` is user-facing,
+  `EMBEDDING.md` owns embedding syntax, and `AGENTS.md` owns project map and
+  skill routing.
+
+### C. Embedding-Specific Documentation
+
+- **Instruction forms match parser behavior.** Do not document unsupported syntax.
+- **Malformed examples name the actual failure.** Prefer concrete reasons such
+  as invalid XML, missing tag end, missing closing tag, missing code fence, or
+  unclosed code fence.
+- **Line-number claims are checked.** Parser errors should point to the
+  instruction start line.
+- **Mode behavior is explicit.** Embed mode writes changed docs; check mode is
+  read-only and reports stale docs.
+- **Fixtures remain readable.** Markdown fixtures under `test/resources/docs/`
+  should be small and named after the behavior they represent.
+
+### D. Skills And Agent Docs
+
+- **Skill frontmatter is compact and trigger-focused.** `name` is hyphen-case
+  and matches the directory. `description` explains when to use the skill.
+- **Skill body follows the pattern.** Prefer role intro, use cases,
+  fast path or workflow, checks/policy sections, repo notes, and output format.
+- **Avoid duplicated policy.** Keep language policy in `go-engineer`, test
+  policy in `go-tester`, documentation authoring policy in `writer`,
+  documentation review policy in `review-docs`, and project map in `AGENTS.md`.
+- **No task-plan references.** Skills should point at durable files and source
+  paths, not temporary task plans.
+
+## Output Format
+
+Return three sections, in this order:
+
+- **Must fix** - broken links, documented commands or syntax that are false,
+  missing required doc comments on changed functions, or Markdown structure
+  that prevents correct rendering.
+- **Should fix** - unclear comments, duplicated policy, stale package maps,
+  inconsistent terminology, orphaned one-word final lines, overbroad inline
+  comments, or examples that are technically right but likely to mislead.
+- **Nits** - wording, wrapping, minor style, or handoff notes for
+  `go-engineer` / `go-tester`.
+
+For each finding, cite the file and line, quote the relevant text, explain the
+impact, and show the recommended rewrite. If a section is empty, write `None.`
+
+End with a one-line verdict: `APPROVE`, `APPROVE WITH CHANGES`, or
+`REQUEST CHANGES`.
diff --git a/skills/review-docs/agents/openai.yaml b/skills/review-docs/agents/openai.yaml
new file mode 100644
index 0000000..0a8d256
--- /dev/null
+++ b/skills/review-docs/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review Docs"
+  short_description: "Review embed-code-go documentation"
+  default_prompt: "Use $review-docs to review documentation changes in embed-code-go."
diff --git a/skills/writer/SKILL.md b/skills/writer/SKILL.md
new file mode 100644
index 0000000..c583361
--- /dev/null
+++ b/skills/writer/SKILL.md
@@ -0,0 +1,107 @@
+---
+name: writer
+description: >
+  Writes, edits, and restructures embed-code-go documentation. Use when asked
+  to create or update README.md, EMBEDDING.md, AGENTS.md, skills, Markdown
+  fixtures, contributor notes, examples, command snippets, Go doc comments, or
+  inline explanatory comments. Verifies documentation claims against current Go
+  code, tests, fixtures, and project flows.
+---
+
+# Write documentation (repo-specific)
+
+## Decide the Target and Audience
+
+- Identify the target reader: CLI user, contributor, maintainer, or agent.
+- Identify the task type: new doc, update, restructure, or documentation audit.
+- Identify the acceptance criteria: what is correct when the reader is done?
+- Ask clarifying questions before editing if the audience, scope, or expected
+  output file is unclear.
+
+## Choose Where The Content Should Live
+
+- Prefer updating an existing document over creating a new one.
+- Put project entry-point and usage content in `README.md`.
+- Put embedding syntax, source markers, patterns, fences, separators, comment
+  modes, and examples in `EMBEDDING.md`.
+- Put project flow, package ownership, skill routing, and repository-level
+  invariants in `AGENTS.md`.
+- Put language, testing, writing, and review procedures in the relevant
+  `skills/<name>/SKILL.md`.
+- Put API or helper behavior that belongs with code in Go doc comments.
+- Put parser and embedding fixtures under `test/resources/` only when they are
+  part of tests or examples already in scope.
+
+## Verify Against Project Flows
+
+- For CLI flags and modes, check `main.go`, `cli/cli.go`, and
+  `cli/cli_validation.go`.
+- For YAML configuration, check `cli/`, `configuration/`, and config fixtures
+  under `test/resources/config_files/`.
+- For embedding syntax, check `embedding/parsing/`, `embedding/processor.go`,
+  `embedding/parsing/instruction.go`, and `EMBEDDING.md`.
+- For source fragments and patterns, check `fragmentation/`,
+  `embedding/parsing/pattern.go`, and relevant source fixtures.
+- For comments modes, check `embedding/commentfilter/`.
+- For examples that claim command output or write behavior, verify with tests or
+  a focused `go run ./main.go ...` command when practical.
+
+## Follow Local Documentation Conventions
+
+- Use fenced code blocks for commands, YAML, Markdown, and source examples.
+- Render file paths, package paths, flags, config keys, instruction attributes,
+  function names, and command names as code.
+- Keep headings hierarchical: one top-level `#`, then ordered levels without skips.
+- Preserve the existing link style of the file being edited. Use local relative
+  links for repository files. Prefer reference-style links for long external
+  URLs when they improve readability.
+- Keep examples small enough to verify and copy.
+- Use consistent terminology: embed mode, check mode, embedding instruction,
+  code fence, fragment, source root, docs root, include pattern, exclude pattern.
+- Do not leave orphans in prose: no paragraph, list item, or table cell should
+  end with a final line containing only one word. Reflow or rewrite the text.
+- Do not duplicate long explanations between `README.md`, `EMBEDDING.md`, and
+  `AGENTS.md`; link to the owning document instead.
+
+## Go Doc Comment Guidance
+
+- Every new or changed function and method should have a useful doc comment in
+  this project, including unexported functions.
+- Exported comments start with the exact declaration name.
+- Unexported comments state intent and start with the function name when it
+  reads naturally.
+- Document non-obvious state transitions, filesystem writes, returned errors,
+  panics, and parser constraints.
+- Do not restate the signature or narrate obvious assignments.
+- Inline comments in production Go should explain why a constraint exists, not
+  what the next line does.
+
+## Make Docs Actionable
+
+- Prefer executable steps, expected outcomes, and concrete examples over broad descriptions.
+- Include prerequisites such as Go version, working directory, fixture location,
+  or mode when they are easy to miss.
+- When documenting failure behavior, include the concrete reason and where the
+  user should look.
+- When documenting architecture, describe ownership boundaries and the normal
+  flow rather than every helper function.
+
+## Validate Changes
+
+- Verify every referenced path exists.
+- Verify flags, config keys, defaults, and instruction attributes against code.
+- Verify Markdown examples and local links.
+- Run `go test ./...` when documentation changes depend on behavior described by
+  tests or fixtures.
+- Run a focused `go run ./main.go ...` scenario when adding or changing a CLI example.
+
+## Output Format
+
+When writing documentation:
+
+1. State the target audience and file location.
+2. Summarize the documentation changed.
+3. List source files, tests, or fixtures used to verify claims.
+4. Report validation commands run and any remaining unverified claims.
+
+Never commit, push, tag, or rewrite Git history.
diff --git a/skills/writer/agents/openai.yaml b/skills/writer/agents/openai.yaml
new file mode 100644
index 0000000..b032a82
--- /dev/null
+++ b/skills/writer/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Writer"
+  short_description: "Write embed-code-go documentation"
+  default_prompt: "Use $writer to write or update documentation in embed-code-go."