x-cmd x-cmd Advise Writing Guide
This is the live instruction for AI agents writing
adv/index.ymlfiles. For the full spec, runx advise spec show. For rule-based verification, runx 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 |
| No builtin help | `-h |
| 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
<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
- Clarity over brevity — say what the command does fully, then trim noise
- Scenario-first TLDR — each example targets one real use case, not parameter permutations
- First TLDR = simplest — no format flags, no extra options; pure natural usage
- Format flags grouped early — show
--csv,--tsvonce each in early TLDRs, then drop them - 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 |
<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
x advise spec show # full spec in TTY
x advise spec show | cat # plain text for piping
2. Initialize template
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
# 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
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>: disableis 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:
x rule check -r /path/to/advise/lib/spec/resource/rule/ adv/index.yml
Reference Commands
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