agentleFS
Sign inStart free
sunholo-datasunholo-data/ailang/.claude/skills/cli-doc-maintainer/SKILL.md

cli-doc-maintainer

Skill38 starsChanged 7 days agoApache-2.0View on GitHub

Keep the AILANG CLI and its docs true to the dispatch table. Use when adding or renaming a command, adding a flag or env var, auditing CLI docs, fixing a doc that cites a command the binary rejects, or when `ailang --help` and a page disagree.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Commit the page with the code.

    line 19

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

CLI Documentation Maintainer

There is nothing here to keep in sync by hand any more. cmd/ailang/commands.go is the only place a command name is written down; ailang --help, every group's help, and docs/docs/reference/cli.md are all rendered from it. This skill is the map of which instrument answers which question — not a set of audits you run.

Adding or changing a command

  1. Edit the Command row in cmd/ailang/commands.go (or commands_language.go / commands_platform.go / commands_eval.go, which assemble it). Name, Aliases, Group, Hidden, Language, Summary.
  2. make docs-cli — regenerates docs/docs/reference/cli.md.
  3. Commit the page with the code. make check-cli-docs fails if they disagree, and so does go test ./cmd/ailang/..., which CI already runs.

A command filed in a group keeps its top-level spelling (D1). Do not rename a route: 593 fleet references call ailang messages, 332 ailang coordinator, 216 ailang chains. The caller sweep is a separate, later change.

Which instrument answers which question

QuestionInstrument
Does the reference page match the table?make check-cli-docs (byte-compares a fresh render against the checked-in page)
How many commands does ailang --help show?make simplicity-metrics-fast → commands_top_level, gate 20
Does every command answer --help?same → help_exit0_rate, gate 100
How many spellings answer "machine-readable output"?same → output_format_spellings, gate 4 (a ratchet; cmd/ailang/output_flags.go is the design record)
Does a teaching prompt cite a command the binary rejects?make check-prompt-commands
Is an environment variable documented?make docs-env regenerates docs/docs/reference/env-vars.md from internal/config's Registry; env_vars_documented_pct gates it at 100

Never probe with a captured token

Auditing docs means running <name> --help for bare command names only, read out of the binary's own generated help and validated against ^[a-z][a-z0-9-]*$ first. The first version of tools/check_prompt_commands.sh passed a token it had scraped from text, and two faults compounded: [a-z0-9-]+ matches a flag (- is literal inside a bracket expression), so ailang test --format json yielded the opener ailang test --format; and ailang test --format --help does not print help, it runs the test suite. Several ailang test processes ground for half an hour. tools/check_prompt_commands.sh and tools/simplicity_metrics.sh both carry the safe pattern — copy one of them rather than writing a third.

Three audit scripts were retired (M-V1-SIMPLIFY-S5 M6)

audit_commands.sh, suggest_improvements.sh and audit_env_vars.sh all measured cmd/ailang/help.go as a hand-written file and main.go as a case switch. S5 M1 generated the first and emptied the second, so by M6 they were not merely stale, they were actively wrong: audit_commands.sh read "Commands in main.go: 1" and demanded that an empty string be documented; suggest_improvements.sh asked for "See also:" cross-references in generated output; audit_env_vars.sh reported 272 variables as undocumented by comparing against a help.go that has not listed environment variables since S4 moved them to internal/config's Registry. The gates in the table above replace all three, structurally. Note for anyone reviving them: BSD grep has no \s, which two of the three used.

resources/best_practices.md and resources/help_template.md describe how to hand-write help.go's prose and are pre-S5 history; they are not instructions for today's CLI.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free