cs-guide

Original：🇨🇳 Chinese

Translated

Write or update external guide documents for the project —— dev-guide (for contributors/integrators/downstream developers) and user-guide (for end users). The output is stored in the project's docs/ directory, maintained alongside the code, and searchable by search tools. Difference from libdoc: guidedoc is task-oriented ("How to do Y with X"), while libdoc is reference-oriented ("What each part of X looks like"). Trigger scenarios: When the user says "write documentation", "developer guide", "user guide", or proactively push at the end of feature-acceptance.

3installs

Sourceliuzhengdongfortest/codestable

Added on2026-04-23

NPX Install

npx skill4agent add liuzhengdongfortest/codestable cs-guide

SKILL.md Content (Chinese)

View Translation Comparison →

cs-guide

Code solves problems, and documentation enables others to use it to solve problems. Spec files record "what was done and why it was done", but downstream developers and end users don't need to, and shouldn't, read specs —— they need role-specific, publishable guides.

guidedoc is exactly the practice of turning specs and code into guides that readers can actually use.

Two Tracks

Track	Target Readers	Typical Content	Output Path
`dev-guide`	Contributors, integrators, downstream developers	Local setup, architecture explanation, API description, extension methods	`docs/dev/{slug}.md`
`user-guide`	End users	Feature overview, operation steps, concept explanation, FAQs	`docs/user/{slug}.md`

Choose the track based on "who will read it", not "whether it's about interfaces or steps" —— The same feature often requires two versions: API changes go into dev-guide, and corresponding user operations go into user-guide.

The paths
docs/dev/
and
docs/user/
are default conventions. Follow the project's existing docs structure if it has one —— confirm this before starting.

Trigger Timing

Scenario	Description
End of feature-acceptance	Proactively push according to `codestable/reference/shared-conventions.md` : Ask "Need to update dev-guide?" if there are changes in Section 2 (interface contract) of the solution doc; ask "Need to update user-guide?" if there are changes in Section 1 (user-visible behavior) of the solution doc
Active trigger by user	"Write documentation", "guidedoc", "Add a developer guide"
After onboarding completion	Trigger this workflow for new repositories to complete the basic documentation skeleton

Only send one proactive push message. Stop if the user says "no" —— repeated pushes will make users feel the AI is overstepping.

Involved Paths

The output of guidedoc is not under
codestable/
—— Guides are publishable products for external readers, separated from spec artifacts.

dev-guide →
```
docs/dev/{slug}.md
```
user-guide →
```
docs/user/{slug}.md
```

File naming:

{slug}.md

(lowercase English + hyphens, no date prefix) —— Guides are continuously updated and managed by topic rather than creation date.

Search for existing guides:

python codestable/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current
python codestable/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug}

YAML frontmatter

yaml

---
doc_type: dev-guide | user-guide
slug: {English description, hyphen-separated}
component: {Associated module name or feature slug}
status: draft | current | outdated
summary: {One-sentence description of what this document covers}
tags: []
last_reviewed: YYYY-MM-DD
---

Three states for

status

:

```
draft
```
: Initial draft pending review
```
current
```
: Currently valid
```
outdated
```
: Corresponding code has changed, but the documentation hasn't kept up (retain the original text, mark it and push for updates)

Document Format

dev-guide Body Structure

markdown

## Overview
A paragraph describing the feature's positioning and applicable scenarios.

## Prerequisites
Environments, dependencies, or configurations required to integrate this module (if any).

## Quick Start
Minimal runnable example. Code first, text as supplement.

## Core Concepts
(Optional) Key terms and design decisions needed to understand the behavior of interfaces/API/modules.

## Interface Reference
Main APIs, configuration options, events, hooks. Presented in tables or itemized lists.

## Common Scenarios
2-4 code examples for actual use cases, covering happy paths and common boundaries.

## Known Limitations & Notes
(Optional) Boundaries, performance considerations, workarounds for known bugs.

## Related Documents
Links or descriptions of associated user-guide, solution doc, architecture doc, or external references.

user-guide Body Structure

markdown

## Feature Introduction
A paragraph describing what the feature is and what problem it solves.

## Preconditions
(Optional) Prerequisites before use (account permissions, required prior operations, etc.).

## How to Use
Step-by-step operations. One step per line, with screenshot placeholders for key operations (`![Description](./assets/xxx.png)` or note "Screenshot needed here").

## FAQs
Q: ...
A: ...

## Related Features
(Optional) Jump links or descriptions of associated features.

Workflow Steps

Step 1: Clarify Task Scope

Confirm three things:

Track: dev-guide / user-guide / both
Coverage: Write a new one or update an existing one
Information Sources: Is the solution doc already available? Are there existing guides for the same component? Which code needs to be read?

Step 2: Collect Inputs

In parallel:

Read the solution doc (focus: Section 0 Terminology, Section 2 Interface Contract, Section 1 User-Visible Behavior)
Use
```
search-yaml.py
```
to search docs/ and confirm if there are existing guides for the same component

If an existing guide is marked

outdated

→ The task is defined as update rather than create new.

Step 3: Draft

Draft according to the corresponding track structure, set

status

to

draft

in the frontmatter first.

Constraints:

Only include content targeted at the intended readers in the body —— Do not copy "implementation tips" or internal design from the solution doc. Different readers have different focuses, mixing spec content into guides will make them lose focus
Keep terminology consistent with Section 0 of the solution doc
Code examples must come from actual code, do not fictionalize interfaces

Step 4: User Review

Show the draft and confirm section by section on coverage, description accuracy, and whether there is content that readers can't understand.

Step 5: Finalize

After user approval:

Write to the corresponding path
Change
```
status
```
from
```
draft
```
to
```
current
```
, fill in
```
last_reviewed
```
with the current date
When updating existing documents: Make small changes directly in the original file, fill in
```
last_reviewed
```
with the current date; for major changes (restructuring, adjusting reader positioning), first mark the old document's
```
status
```
as
```
outdated
```
for reference, then write a new one

Relationship with Other Workflows

Source	Relationship
`cs-feat-accept`	After acceptance, proactively push according to `shared-conventions.md` : Push dev-guide for interface changes, push user-guide for user-visible behavior changes
`cs-feat-design`	Section 2 of the solution doc is the main information source for dev-guide; Section 1 is the main information source for user-guide
`cs-onboard`	Complete the basic documentation skeleton after new repository onboarding
`cs-arch` (check mode)	When inconsistency between design and code is detected, the corresponding guide should be marked `outdated` synchronously
`cs-decide`	Technical selections referenced in dev-guide should come from decisions, not independently invented
`cs-trick`	If usage examples in dev-guide overlap with tricks, cross-reference instead of repeating
`cs-libdoc`	Guides reference libdoc entries for detailed references; libdoc is part reference, guidedoc is task tutorial

Common Pitfalls

❌ Copy "implementation tips" from the solution doc directly into dev-guide —— that's internal spec
❌ Create a new guide without checking existing ones —— may cause content conflicts
❌ Leave
```
status
```
as
```
draft
```
after writing the guide —— must change to
```
current
```
when finalizing
❌ Keep related guides as
```
current
```
even though the code has been updated —— should mark as
```
outdated
```
and push for updates
❌ Have highly overlapping content between dev-guide and user-guide —— overlap indicates that one of the guides has incorrect positioning
❌ Store spec information (invariants, test constraints, root cause analysis) in guides —— such content belongs to
```
codestable/
```

cs-guide

NPX Install

Tags

SKILL.md Content (Chinese)

cs-guide

Two Tracks

Trigger Timing

Involved Paths

YAML frontmatter

Document Format

dev-guide Body Structure

user-guide Body Structure

Workflow Steps

Step 1: Clarify Task Scope

Step 2: Collect Inputs

Step 3: Draft

Step 4: User Review

Step 5: Finalize

Relationship with Other Workflows

Common Pitfalls