# Spec

> x-cmd Advise Writing Guide

- Skill: `x-cmd/spec` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add x-cmd/spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-cmd/spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: x-cmd (https://skillmd.com/u/x-cmd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/x-cmd/spec

---


# x-cmd Advise Writing Guide

> This is the **live instruction** for AI agents writing `adv/index.yml` files.
> For the full spec, run `x advise spec show`.
> For rule-based verification, run `x advise spec lint`.

---

## Core Principles

| Principle | Rule |
|-----------|------|
| **Options first** | In all examples (synopsis, tldr, desc), options MUST precede arguments. `x mod --opt arg` ✅, `x mod arg --opt` ❌ |
| **Root-level subcmds** | Subcommands are defined at root, NOT wrapped under `<subcmd>:` |
| **Preserve order** | Never reorder subcmd aliases. `c|cp|copy` stays `c|cp|copy` |
| **No builtin help** | `-h|--help` is handled by code; do NOT declare it in advise |
| **Efficiency modules** | Only `assert`, `is`, `str` are efficiency modules. Mark with `<meta>: <subcmd-help>: disable`. All TLDR at root only. |
| **YAML safety** | Quote strings containing `:`, `!`, `&`, `*`, or leading `-` |

---

## Field Quick Reference

```yaml
<name>:
  <modname>:
  cn: 中文名
  en: English name

<synopsis>:                 # MODULE level only
  - x <mod> [subcmd] [options]:

<desc>:
  cn: |
    Description.
  en: |
    Description.

<tip>:                      # List of tips, module or subcmd level
  - cn: "Tip content"
    en: "Tip content"

<tldr>:                     # At least 3 items (simple) or 8+ (complex)
  - cmd: x <mod> <subcmd>
    cn: "示例: description"
    en: "Example: description"

<subcmd:Category>:          # Display grouping only
  - subcmd1
  - subcmd2

# Subcommands at ROOT level
subcmd1:
  <desc>:
    cn: ...
    en: ...
  <1>:                        # Positional arg
    <desc>: ...
    <exec>: ___x_cmd_advise__file
  --option|-o:
    <desc>: ...
```

**Required fields**: `<name>`, `<synopsis>`, `<desc>`, `<tldr>` (minimum 3).

---

## Writing Priority

1. **Clarity over brevity** — say what the command does fully, then trim noise
2. **Scenario-first TLDR** — each example targets one real use case, not parameter permutations
3. **First TLDR = simplest** — no format flags, no extra options; pure natural usage
4. **Format flags grouped early** — show `--csv`, `--tsv` once each in early TLDRs, then drop them
5. **Information density** — experts first; AI and agents need to know the module's ceiling

---

## Common Error Patterns

| Error | Fix |
|-------|-----|
| `<subcmd>:` wrapper | Define subcmds at root level |
| Changed alias order | Keep original: `c|cp|copy` not `c|copy|cp` |
| `<synopsis>` in subcmd | Use `<1>`, `<2>`, `<n>` in subcmds; `<synopsis>` is module-only |
| Efficiency TLDR in subcmd | Move all TLDR to root for assert/is/str |
| Unquoted `:` in desc | Wrap in quotes: `"Backend: value"` |
| Declaring `-h\|--help` | Remove; handled by `lib/main` |

---

## Workflow

### 1. Read the spec
```bash
x advise spec show            # full spec in TTY
x advise spec show | cat      # plain text for piping
```

### 2. Initialize template
```bash
x advise spec init            # copies tmpl.mod.yml → adv/index.yml
```

### 3. Write / edit `adv/index.yml`
Follow the field order: `<name>` → `<meta>` → `<synopsis>` → `<desc>` → `<tip>` → `<tldr>` → `<subcmd:Category>` → subcmd definitions.

### 4. Lint and verify
```bash
# From module directory
x advise spec lint

# Or specify path
x advise spec lint --path /path/to/module
```

Lint generates `advise.jso` and renders help. If it passes, the advise is structurally valid.

### 5. Install to local x-cmd
```bash
x scotty mod install          # installs adv/index.yml into x-cmd user directory
```

---

## Efficiency Module Checklist

Only `assert`, `is`, `str` qualify. Check before marking:

- [ ] `<meta>: <subcmd-help>: disable` is present
- [ ] ALL TLDR at root level
- [ ] NO `<tldr>` under any subcmd
- [ ] Subcmds have only `<desc>` (no options, no tldr)

---

## Standard Module Examples

Study these for specific patterns:

| Module | Pattern |
|--------|---------|
| `bwh` | Multi-part advise with `<ref>` |
| `line` | Subcmd categories, `_` suffix tip at module level |
| `dbnomics` | Scenario TLDR, auto mode, format flags |
| `assert` | Efficiency module |
| `str` | Efficiency module, pipe + arg dual input |

---

## Rules (x rule integration)

`rule/advise.rule.yml` lives next to this spec. Key rules:

| Rule | Level | Check |
|------|-------|-------|
| `ADV-syntax-indent` | error | 2-space indent, no tabs |
| `ADV-field-name-required` | error | `<name>` has cn + en |
| `ADV-field-tldr-min` | error | ≥3 TLDR items |
| `ADV-option-prefix` | error | Options precede args in all examples |
| `ADV-modify-order` | error | Subcmd alias order unchanged |
| `ADV-efficiency-tldr-root` | error | Efficiency TLDR only at root |

Run rule checks after editing:
```bash
x rule check -r /path/to/advise/lib/spec/resource/rule/ adv/index.yml
```

---

## Reference Commands

```bash
x advise spec show            # display spec
x advise spec init            # create tmpl.mod.yml
x advise spec lint            # validate and render
x advise ls                   # list loaded advise files
x advise cat <name>           # view advise.jso content
x advise which <name>         # path to advise.jso
```