# Docs

> >

- **Type:** Skill
- **Install:** `agentstack add skill-yulonghe97-ystack-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yulonghe97](https://agentstack.voostack.com/s/yulonghe97)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yulonghe97](https://github.com/yulonghe97)
- **Source:** https://github.com/yulonghe97/ystack/tree/main/skills/docs

## Install

```sh
agentstack add skill-yulonghe97-ystack-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /docs — Update Documentation

You update documentation to reflect completed, verified work. Docs describe what the system IS — never what's planned.

## Phase 0: Detect What Changed

1. Get the diff to understand what code changed:
   ```bash
   # Resolve the repo's default branch dynamically
   BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' || echo main)
   git diff "$BASE"...HEAD --stat
   ```

2. Read `.context//DECISIONS.md` to understand the feature intent.

3. Read `.context//PLAN.md` for the success criteria — these tell you what was built.

4. **Read the progress file** — `.ystack/progress/.md` for the affected module. Features marked `[x]` are completed and may need doc updates. Features still `[ ]` must NOT be documented. The progress file is the gate between implementation and documentation.

## Phase 1: Map Changes to Docs

Identify which documentation pages are affected.

1. **Read the module registry** (`.ystack/config.json`) to find the module-to-doc mapping. Match changed file paths against module `scope` globs. If no registry exists, fall back to scanning `docs/src/content/_meta.ts`.

2. **Map changed code paths to doc pages:**

   | Code path pattern | Likely doc page |
   |-------------------|----------------|
   | `packages//` | `docs/src/content//` or `docs/src/content/shared//` |
   | `apps//` | `docs/src/content//` |
   | `packages/db/src/schema*` | Data model sections across affected modules |
   | `apps/api/src/routes/` | API module + any module whose API changed |

3. **Read the affected doc pages** before modifying them. Understand what's currently documented.

## Phase 2: Update Affected Pages

For each affected doc page, update ONLY the sections impacted by the new feature.

**What to update:**

| Change type | Doc section to update |
|-------------|----------------------|
| New database column/table | Data Model section — add to table/columns/notes table |
| New API endpoint or field | Dependencies section — update "Provides" list, or relevant sub-module page |
| New UI component or page | Sub-modules table — add or update entry |
| New module dependency | Dependencies section — update "Needs" table |
| Changed flow or behavior | Flows section — update Mermaid diagram and numbered explanation |
| New sub-module | Sub-modules table + create new sub-module page if significant |

**What NOT to update:**
- Sections unrelated to the feature
- "Purpose" section (unless the module's core responsibility changed)
- "Team" section
- "Scope" section (unless something moved in/out of scope)

**Writing rules:**
- Present tense, active voice: "The gateway normalizes messages" not "Messages will be normalized"
- Purpose over implementation: describe what it does and why, not how the code works
- No version language: no "v1", "v2", "Phase 1", "new", "recently added"
- No planning language: no "planned", "coming soon", "TODO", "will be", "in progress"
- Link, don't recap: reference other pages instead of repeating their content
- Use cross-references: `[Module Name](/module-path)` for every module mention

**Diagram rules (if updating Mermaid diagrams):**
- Use the right type: `sequenceDiagram` for multi-actor flows, `graph TB/LR` for architecture, `erDiagram` for data models
- Label edges: `-->|"what flows"|` not just `-->`
- Keep under 20 nodes — split if bigger
- Every diagram needs a text explanation below it

## Phase 3: Update Navigation

If you created a new doc page, update the navigation config for the docs framework in use:

**Nextra** — add to `_meta.ts`:
```typescript
// docs/src/content//_meta.ts
export default {
  index: "Overview",
  "existing-page": "Existing Page",
  "new-page": "New Page",        // ← add here, object key order = sidebar order
};
```

**Fumadocs** — add to `meta.json` or use frontmatter ordering:
```json
// content/docs//meta.json
{
  "pages": ["index", "existing-page", "new-page"]
}
```

Check `.ystack/config.json` `docs.framework` to know which format to use.

## Phase 4: Update Structural Files

If the feature changed module responsibilities, dependencies, or structure, also update:

1. **Root `CLAUDE.md`** — if the Structure section or Commands changed
2. **Root `AGENTS.md`** — mirror CLAUDE.md changes

Most features don't require root structural file updates. Only update these if the module's role or boundaries shifted.

## Phase 5: Update Per-Package Context Files

For each module whose code changed in the current diff, update its `AGENTS.md` (and `CLAUDE.md` if `.ystack/config.json` has `"runtime": "claude-code"`).

If the file doesn't exist yet, create it. If it exists, update it.

### What to include

Read the package's actual code and populate:

1. **Key Files** — list the important entry points with one-line descriptions:
   ```markdown
   ## Key Files

   - `src/index.ts` — public API surface
   - `src/schema.ts` — database schema (drizzle)
   - `src/routes/payments.ts` — HTTP handlers
   - `src/errors.ts` — domain error types
   ```

2. **Conventions** — patterns observed in the code, stated as rules:
   ```markdown
   ## Conventions

   - All exports go through `src/index.ts`
   - Error types defined in `src/errors.ts`, re-thrown at API boundary
   - Tests colocated: `src/__tests__/.test.ts`
   - Zod schemas validate all external input
   ```

### Rules

- **References, not explanations.** Point to files and state patterns. Don't explain what the code does — that's what the docs site is for.
- **Max ~30 lines.** If it's longer, you're writing too much.
- **Only update for changed modules.** Don't rewrite every package's context file on every run.
- **No stale content.** If a file was renamed or removed, update the reference. If a convention changed, update the rule.
- **CLAUDE.md mirrors AGENTS.md** unless there are Claude-specific hints to add (e.g., "use Agent tool for parallel execution in /go").

## Phase 6: Verify

1. Check that all cross-reference links point to existing pages:
   ```bash
   # Extract links from updated docs and verify targets exist
   grep -oP '\[.*?\]\((/[^)]+)\)' docs/src/content//*.mdx
   ```

2. Confirm no planning language leaked in:
   ```bash
   grep -i -E '(coming soon|planned|todo|will be|in progress|phase [0-9])' docs/src/content//*.mdx
   ```

3. Present a summary of what was updated:
   ```
   ## Documentation Updates

   ### Modified
   - docs/src/content/shared/payments/index.mdx
     - Added `refundReason` to Data Model table
     - Updated Refund Flow sub-module description

   ### Created
   - (none)

   ### Structural files
   - (no changes needed)
   ```

---

## Delegating to Existing Skills

If the project has its own documentation skills (e.g., `docs-update`, `docs-module`, `docs-page`), prefer delegating to them. They know the project-specific conventions.

- **Updating existing pages** → delegate to `docs-update` if available
- **Creating a new module's docs** → delegate to `docs-module` if available
- **Writing a single new page** → delegate to `docs-page` if available

If no project-specific doc skills exist, follow the process above.

---

## What This Skill Does NOT Do

- **Does not document planned features.** Only completed, verified work.
- **Does not rewrite entire pages.** Updates only affected sections.
- **Does not create module scaffolds.** That's `/scaffold`.
- **Does not create PRs.** That's `/pr`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yulonghe97](https://github.com/yulonghe97)
- **Source:** [yulonghe97/ystack](https://github.com/yulonghe97/ystack)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yulonghe97-ystack-docs
- Seller: https://agentstack.voostack.com/s/yulonghe97
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.