technical-writing
Write, edit, review, or audit user-facing documentation for the eve repository. Use for changes under docs/, documentation tied to eve APIs or CLI behavior, docs work based on Slack or support feedback, and requests to make eve docs clearer, more natural, or less AI-patterned while verifying claims against current source, tests, CLI help, public releases, and repository conventions.
- License 许可
- Apache-2.0
- 所属仓库
- vercel/eve
- 最近更新
- 2026-11-15
- Stars
- ★ 5.9k
- Forks
- 656
01 前言 Front Matter
- name
- technical-writing
- metadata
- { "internal": true }
- description
- Write, edit, review, or audit user-facing documentation for the eve repository. Use for changes under docs/, documentation tied to eve APIs or CLI behavior, docs work based on Slack or support feedback, and requests to make eve docs clearer, more natural, or less AI-patterned while verifying claims against current source, tests, CLI help, public releases, and repository conventions.
02 资源文件 7
- 参考文档agents/openai.yaml266 B
- 参考文档references/content-types.md3.9 KB
- 参考文档references/editing-workflow.md2.8 KB
- 参考文档references/prose-quality.md3.2 KB
- 参考文档references/review-framework.md3.0 KB
- 参考文档references/style-rules.md7.7 KB
- 参考文档references/writing-workflow.md1.6 KB
03 SKILL.md 正文
Technical writing
Write accurate, task-focused documentation for eve. Treat developers and AI agents as readers: make each section easy to scan, retrieve, and act on without relying on unstated context.
Choose a workflow
- For a new page or full rewrite, read references/writing-workflow.md.
- For targeted or structural changes to existing pages, read references/editing-workflow.md.
- Before finalizing any change, read references/review-framework.md.
- For formatting and terminology, read references/style-rules.md.
- For wording, voice, or AI-pattern concerns, read references/prose-quality.md.
- For page structure, read references/content-types.md when the content type is unclear or changing.
Verify before writing
Do not rely on training data for eve behavior. Use this source hierarchy:
- Current source, public types, and tests in
packages/eve - Current CLI help and setup implementation
- Existing pages under
docs/ - Merged pull requests, changelogs, and release notes
- Research plans under
research/as proposed intent, not shipped behavior - Support evidence such as Slack threads or issues
Use support evidence to identify the reader's problem, not to establish product behavior. Verify commands, flags, API names, defaults, limitations, and examples against the current repository. For a docs-only change, also compare the implementation with the latest public release so the docs do not announce branch-only behavior. When docs accompany product code in the same change, state that dependency during review. If a claim cannot be verified, omit it or report the missing owner or source. Never leave [VERIFY] markers in a completed docs change.
Follow eve conventions
- Write
evelowercase, including headings and sentence starts when practical. - Use exact public names such as
defineAgent,eve dev, andeve add channel/slack. - Distinguish the root agent, the built-in
agenttool, declared subagents, and remote agents. They have different inheritance and execution semantics. - Distinguish eve connections from Vercel Connect, the model-facing
Workflowtool from authored Vercel Workflows, and durable session state from sandbox filesystem or attachment storage. - Name diagnostic surfaces precisely: Vercel runtime logs, Agent Runs, OpenTelemetry,
eve logs, andeve tracesare not interchangeable. - Treat
docs/**as published documentation. Updatedocs/meta.jsonwhen navigation changes. - Keep
.mdfiles framework-agnostic. Use MDX components only in.mdxfiles and only when nearby pages establish the convention. - Preserve published routes and heading anchors when possible. When moving a page, update authored links and add permanent redirects for old HTML and Markdown URLs.
- Prefer TypeScript examples. Include imports and language labels, and verify examples against current exports.
- Show only supported commands and flags. Check CLI help or the command implementation before documenting them.
- Link to related pages with descriptive text. Include the critical fact locally because retrieved sections may be read without their links.
- Leave no page orphaned. Every page needs at least one descriptive inbound body link from a related hub or overview page; a
meta.jsonsidebar entry or a routing-table cell alone is not enough. When adding a page, add the inbound link from the page that owns the topic in the same change, and keep every page reachable by following body links fromgetting-started. - Do not document proposed behavior as shipped. Describe unsupported boundaries directly when they affect a user task.
- Describe current behavior only. Migration steps, removed options, and renames belong in changesets and release notes, not in
docs/**. - Document the contract, not the mechanism. Leave out internal modules, algorithms, and data structures unless the reader needs them to configure, debug, or reason about a limit.
Write for the task
- Lead each page and section with the answer or outcome. Feature pages follow the feature page shape in references/content-types.md: opening, minimal example, rules, options, then variants.
- Write prose in the reader's words, not eve's runtime vocabulary. See Plain words in references/style-rules.md.
- Address the reader as
you; use imperative verbs for steps. - Prefer active voice, present tense, concrete nouns, and consistent terms.
- Preserve the author's supported meaning, nuance, and uncertainty. Make the minimum effective edit and leave strong prose alone.
- Keep one page focused on one primary job. Add a section to an existing page when it already owns the task.
- Put the happy path before alternatives and failure modes.
- Add troubleshooting where observed failures cluster around a workflow. Use symptoms, verified causes, and concrete next checks.
- Write self-contained sections. Repeat the full noun in key statements instead of relying on ambiguous pronouns.
- Use specific limits and behavior only when the repository or an authoritative platform source supports them.
Avoid common failures
- Do not invent flags, registry entries, connectors, workarounds, or platform guarantees.
- Do not turn one product request into a new page. First decide whether the gap belongs to docs, product, or both.
- Do not duplicate broad guides when a focused section or cross-link resolves the problem.
- Do not rewrite clear prose merely to match a personal preference.
- Do not manufacture examples, opinions, reactions, or specificity to make prose sound more human.
- Do not use promotional language, rhetorical questions, filler, or claims that a task is easy, simple, or quick.
- Do not use
weunless describing a deliberate Vercel or eve team action.
Finish the change
- Re-read every changed page in full.
- Verify each new technical claim against its source.
- Search for contradictory statements and affected cross-links.
- Confirm added or moved pages have an inbound body link from a related page, so no page is orphaned.
- Run the review workflow.
- Check changed prose against the prose-quality reference when wording changed materially.
- Run
pnpm docs:checkwhen preparing to push, unless the user requests earlier validation.
04 同仓库更多 Skills
writing-quality
The review rubric: writing-quality rules and reference lists for judging a content draft, covering AI-sounding phrasing, bloated wording, structure, and web-content specs. Load at the start of every review.
writing-quality
Writing-quality guardrails for any prose the agent drafts or edits: blog posts, page copy, Notion drafts, release notes, marketing text. Use this skill whenever writing or revising content meant for humans to read, to keep the prose natural, plain, and free of AI-sounding phrasing. Not needed for code, queries, or structural CMS work.
seo-aeo-best-practices
SEO and AEO best practices for metadata, Open Graph, sitemaps, robots.txt, hreflang, JSON-LD structured data, EEAT, and content optimized for search engines and AI answer surfaces. Use this skill when implementing page SEO, technical SEO, schema markup, international SEO, AI-overview readiness, or improving content for Google, ChatGPT, Perplexity, and similar assistants.
sanity-best-practices
Sanity development best practices for schema design, GROQ queries, TypeGen, Visual Editing, images, Portable Text, Studio structure, localization, migrations, Sanity Functions, Blueprints, and framework integrations such as Next.js, Nuxt, Astro, Remix, SvelteKit, Angular, Hydrogen, and the App SDK. Use this skill whenever working with Sanity schemas, defineType or defineField, GROQ or defineQuery, content modeling, Presentation or preview setups, Sanity-powered frontend integrations, Sanity Functions, documentEventHandler, defineDocumentFunction, defineMediaLibraryAssetFunction, @sanity/functions, @sanity/blueprints, sanity.blueprint.ts, event-driven content automation, or when reviewing and fixing a Sanity codebase.
portable-text-serialization
Render and serialize Portable Text to React, Svelte, Vue, Astro, HTML, Markdown, and plain text. Use when implementing Portable Text rendering in any frontend framework, building custom serializers for non-standard block types, converting Portable Text to HTML strings server-side, converting Portable Text to Markdown, extracting plain text from Portable Text, or troubleshooting rendering issues with marks, blocks, lists, or custom types.
portable-text-conversion
Convert HTML and Markdown content into Portable Text blocks for Sanity. Use when migrating content from legacy CMSs, importing HTML or Markdown into Sanity, building content pipelines that ingest external content, converting rich text between formats, or programmatically creating Portable Text documents. Covers @portabletext/markdown (markdownToPortableText), @portabletext/block-tools (htmlToBlocks), custom deserializers, and the Portable Text specification for manual block construction.