菜单
Guidelines for writing AI agent documentation (skills, CLAUDE.md, README files). Use when creating or updating documentation that will be consumed by AI agents to avoid context window pollution.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Save articles and web pages to a Readplace reading list and read them back as clean, distraction-free text or an AI TL;DR. Use when a user asks to save a link for later, build a reading list, or pull up something they saved to Readplace.
Web adapter conventions for the application domain. Use when working with HTML templates, CSS styles, client-side JavaScript, or SSR patterns. Triggers on changes to .css, .html, .view.html, .client.js files.
Infrastructure Design
Hypermedia contract between Readplace's hutch server and every client that consumes it — the chrome and firefox extensions, the iOS app, the MCP server, and future clients. Use when adding, renaming, or removing an API capability a client consumes, when the server emits or parses Siren responses, or when any client's navigation/action flow changes.
E2E testing conventions using Playwright and the HATEOAS-based test framework. Use when working with E2E tests, files in e2e/ directories, *.e2e*.ts files, or when test errors mention Playwright, HATEOASClient, NavigationHandler, PageAction, or locator timeouts.
Software design and testing conventions that support testability. Use when writing tests, designing testable code, working with dependency injection, or when test coverage issues arise.
| name | ai-agent-editor |
| description | Guidelines for writing AI agent documentation (skills, CLAUDE.md, README files). Use when creating or updating documentation that will be consumed by AI agents to avoid context window pollution. |
Conventions for writing documentation that AI agents consume. The goal is to minimize context window usage while maximizing actionable guidance.
AI agents can inspect the codebase. Guide the agent to discover information rather than duplicating it inline.
<!-- ❌ BAD - Duplicates code -->
type PageComponent = { head: HeadComponent; ... }
<!-- ✅ GOOD - References source -->
See [projects/hutch/src/web/component.types.ts](projects/hutch/src/web/component.types.ts)
<!-- ❌ BAD -->
We execute e2e tests using `pnpm nx run flights:test-ui`...
<!-- ✅ GOOD -->
Inspect `project.json` to understand how e2e tests run.
<!-- ❌ BAD -->
The booking ID uses a 31-character set and weighted sum algorithm...
<!-- ✅ GOOD -->
The booking ID excludes 0, O, 1, I, L to avoid confusion when read over the phone.
See `projects/hutch/src/domain/booking-id.ts` for implementation.
Include inline code examples only when:
| Guideline | Rationale |
|---|---|
| Use concise headings | Scannable navigation |
| Prefer tables over prose | More scannable, less context |
| Link to external specs | Don't re-document standards |
| Avoid | Reason |
|---|---|
| Directory structure diagrams | Stale when files change; use ls |
| Command output examples | Stale with versions; just run the command |
| ASCII workflow diagrams | Hard to maintain; use prose or link externally |
These guidelines apply to this skill itself. When updating ai-agent-editor: