AGENT SKILL

claudeloop-docs

Explains where different kinds of content belong in this repo (CLAUDE.md vs .claude/skills/ vs docs/), how to build and strict-check the MkDocs Material site, and the writing conventions used throughout (Roadmap admonitions, relative links, ADR format). Use this whenever writing or editing any file under docs/, whenever deciding whether new content belongs in CLAUDE.md, a skill, or docs/, whenever the user asks about documentation structure, or before adding a page to mkdocs.yml's nav. Make sure to consult this before adding procedural, multi-step content to CLAUDE.md directly — CLAUDE.md is deliberately kept short and holds only facts; procedures belong in a skill instead, and getting this wrong bloats the context every single session pays for.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 5
Forks
3

01 前言 Front Matter

name
claudeloop-docs
description
Explains where different kinds of content belong in this repo (CLAUDE.md vs .claude/skills/ vs docs/), how to build and strict-check the MkDocs Material site, and the writing conventions used throughout (Roadmap admonitions, relative links, ADR format). Use this whenever writing or editing any file under docs/, whenever deciding whether new content belongs in CLAUDE.md, a skill, or docs/, whenever the user asks about documentation structure, or before adding a page to mkdocs.yml's nav. Make sure to consult this before adding procedural, multi-step content to CLAUDE.md directly — CLAUDE.md is deliberately kept short and holds only facts; procedures belong in a skill instead, and getting this wrong bloats the context every single session pays for.
allowed-tools
Read Grep Glob Bash(mkdocs *)

03 SKILL.md 正文

claudeloop documentation

Where content belongs — the decision table

Content Goes in
An always-true fact, cheap to state, every session needs CLAUDE.md and AGENTS.md — kept deliberately SHORT, routers not manuals
A procedure for working on a specific part of this codebase .claude/skills/<name>/SKILL.md and mirrored to .cursor/rules/<name>.mdc and .agents/skills/<name>/SKILL.md
User-facing "how do I..." docs/getting-started/ or docs/guides/
System design — what exists, how pieces fit docs/architecture/
The reasoning behind ONE specific hard decision docs/architecture/decisions/ — an ADR
Generated API docs docs/reference/api.md via mkdocstrings — never hand-write signatures that already exist as docstrings
Contributor process docs/contributing/
Historical plans, preserved verbatim once superseded docs/plans/

The CLAUDE.md / AGENTS.md / skill dividing line: routers hold facts; skills/rules hold procedures. If you're about to add a multi-step "when doing X, do Y then Z" instruction to CLAUDE.md or AGENTS.md, it belongs in a skill instead — skills load into context only when relevant.

Three agent surfaces (must stay in sync)

Surface Paths
Claude Code CLAUDE.md + .claude/skills/*/SKILL.md
Cursor .cursor/rules/claudeloop-router.mdc (always) + .cursor/rules/claudeloop-*.mdc
Codex AGENTS.md + .agents/skills/*/SKILL.md

PR checklist: when procedural guidance changes, update all three trees in the same PR. No codegen in v1 — manual mirror.

Building and checking the site

pip install -e ".[docs]"
mkdocs serve      # local preview at http://127.0.0.1:8000, live-reloads
mkdocs build --strict   # what CI runs — fails on ANY warning, most commonly a broken link

Run mkdocs build --strict before opening a PR that touches docs/ — it's exactly what docs.yml runs in CI.

Writing conventions

  • Plain markdown only — the extensions enabled in mkdocs.yml (admonitions, code fences, tables) and nothing docs-only-syntax beyond that, because every page must read correctly as plain text on GitHub (CLAUDE.md and the skills link straight to file paths, not built-site URLs).
  • Relative links, not absolute site URLs — so links work both on GitHub and in the built MkDocs site.
  • Explain "why," not just "what." A page restating a function signature the code already shows isn't earning its place — put reasoning a stranger can't get from the code alone into the page. This is exactly the ADRs' purpose.
  • Mark roadmap content with !!! note "Roadmap" at the top of any page describing a not-yet-built milestone, so a reader never mistakes a design intention for current behavior. grep -rl '!!! note "Roadmap"' docs/ finds every page that needs revisiting as a milestone lands.
  • New page → add it to mkdocs.yml's nav: or mkdocs build --strict will not error (an orphaned page is not itself a strict-mode failure) but the page becomes unreachable from the site nav — always add it.

ADR format

Follow the existing files in docs/architecture/decisions/ exactly: NNNN-kebab-case-title.md, sections ## Status / ## Context / ## Decision / ## Consequences, four-digit zero-padded sequential numbering. Add a new ADR when a PR makes a hard, non-obvious design call worth preserving the reasoning for — not for routine changes.

Full reference

docs/contributing/documentation.md.

04 同仓库更多 Skills

the-vibey-project
the-vibey-project/vibey

white-paper-writing

Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks "how should I structure this" for a long-form document.

★ 5
the-vibey-project
the-vibey-project/vibey

prose-technical-mechanics

Use when editing or writing prose at a technical/mechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.

★ 5
the-vibey-project
the-vibey-project/vibey

prose-mechanics

Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate/Jamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix "AI-sounding" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.

★ 5
the-vibey-project
the-vibey-project/vibey

narrative-structure

Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or "how should I structure this story/pitch/presentation" request.

★ 5
the-vibey-project
the-vibey-project/vibey

legal-brief-writing

Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic/neurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.

★ 5
the-vibey-project
the-vibey-project/vibey

journal-publishability-criteria

Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs/paper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.

★ 5