Agent skill

Vocabulary

by xiaolai in xiaolai/nlpm

NLPM noun/verb registry (R51): pick the canonical term, detect vocabulary drift.

ISCAuto-check passedAgent Workflows

Install Vocabulary

skills CLI
$ npx skills add xiaolai/nlpm --skill vocabulary -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install xiaolai/nlpm vocabulary --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/xiaolai/nlpm.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/nlpm/vocabulary .claude/skills/vocabulary && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
vocabulary
GitHub stars
150
Token cost
~3.9k tokens
SKILL.md length
1,732 words
Files
2
Skills in repo
15
Repo updated
First seen
Licence
ISC

At a glance

NLPM noun/verb registry (R51): pick the canonical term, detect vocabulary drift.

  • Works in 5 steps: Add a term only if it has warrant. The… → Re-run the extraction script. python3… → Slot the term. Add a row to the right… → …
  • Agent Workflows work in your project
  • SKILL.md covers How this registry is built, Two scopes (P1), Verbs and Nouns, plus 5 more sections
  • Calls python3

What it does

Vocabulary is an agent skill from xiaolai/nlpm. NLPM noun/verb registry (R51): pick the canonical term, detect vocabulary drift.

Its SKILL.md is about 3.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `registry.yaml`).

It sits in Agent Workflows. The repository describes itself as: Natural-Language Programming Manager — scan, lint, and score NL artifacts with Claude-native quality scoring. The licence is ISC.

When your agent uses it

  • Agent Workflows work in your project

Example prompts

  • “/vocabulary”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Add a term only if it has warrant. The four warrant types come from analysis/vocabulary-design-principles.md P6: literary, user…
  2. Re-run the extraction script. python3 analysis/scripts/extract-vocabulary.py writes analysis/vocabulary-extract/summary.md. New terms…
  3. Slot the term. Add a row to the right table above (internal verb / auditor verb / artifact-class noun / role-noun / output-class noun /…
  4. Cite the file evidence. Every row has an "examples" or "file evidence" column. Cite at least one path.
  5. If retiring a synonym, list it under its canonical verb's "deprecated synonyms" line. Do not silently drop terms; deprecation is itself a…

What it can do on your machine

Read from SKILL.md and the folder at commit bfa2fc2. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Vocabulary loads about 3.9k tokens when it runs. Until then it costs about 23 tokens; SKILL.md has 1,732 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~23
When it runs · the whole SKILL.md, loaded when a task matches
~3.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from xiaolai/nlpm at commit bfa2fc2, republished under its ISC licence (© xiaolai). 1,732 words, ~3,932 tokens.

Download SKILL.mdSave it as .claude/skills/vocabulary/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
vocabulary
description
NLPM noun/verb registry (R51): pick the canonical term, detect vocabulary drift.
version
0.1.0
user-invocable
false

NLPM Domain Vocabulary

The canonical noun-and-verb set NLPM uses to name what it does. Every artifact name, command name, agent name, rule wording, and prose description should draw from this registry. Synonyms are flagged by /nlpm:check and penalized by /nlpm:score.

Sister skill: nlpm:conventions holds upstream Claude Code framework terms (hook events, frontmatter fields, manifest keys). This skill holds NLPM-internal domain language. If a term is from Anthropic's docs, it belongs in conventions. If it is from NLPM's own corpus, it belongs here.


How this registry is built

Every term listed below has literary warrant — it appears in at least one NLPM artifact today, captured by analysis/scripts/extract-vocabulary.py. Re-run that script after adding or renaming artifacts; the freshest output lives at analysis/vocabulary-extract/summary.md. New terms enter the registry only after one of the four warrant types from analysis/vocabulary-design-principles.md (P6) is satisfied — literary warrant alone is the entry bar for terms already in use; new coinages need user, structural, or domain warrant.


Two scopes (P1)

NLPM has two declared scopes. A homonym across them is a boundary, not a collision.

ScopeLives inWhat it operates on
internalcommands/, agents/, skills/, bin/, scripts/, project CLAUDE.mdNLPM's own behavior — scoring, checking, fixing, testing, listing, trending NL artifacts in the current project.
auditor.github/workflows/auditor-*.yml, auditor/The self-evolution pipeline that audits external repos, opens contribution PRs, tracks outcomes, refines rules.

A verb that appears in both scopes (scan, test, discover) carries the same identity criterion in both — these are sanctioned homonyms. A verb that appears in only one scope (audit, contribute, track in auditor; score, check, fix, ls, trend, init in internal) is scope-bound; using it in the other scope requires either renaming or declaring a second scope-specific definition.


Verbs

Internal scope (NLPM commands)
Canonical verbOutputJudgment?Examples in corpus
scorenumber + penalty listno (deterministic)commands/score.md, agents/scorer.md
checkconsistency violation listno (deterministic)commands/check.md, agents/checker.md
testpass/fail against named specsno (deterministic)commands/test.md, agents/tester.md
scanpattern-match findings against a signature databaseno (deterministic)commands/security-scan.md, agents/vague-scanner.md, agents/security-scanner.md
fixmutated artifactno (mechanical)commands/fix.md
lsinventory of artifactsnocommands/ls.md, agents/scanner.md
trendhistory reportnocommands/trend.md
initconfig filenocommands/init.md

Deprecated synonyms (do not use in internal scope):

  • lint, validate → use check (structural) or score (quality)
  • find, search, list → use ls
  • analyze → use score (if quantitative) or pick a more specific verb
  • audit → not in internal scope; live in auditor scope only
Auditor scope (.github/workflows/auditor-*.yml, auditor/scripts/)
Canonical verbOutputJudgment?Examples in corpus
discovercandidate-repo listnoauditor-discover.yml
auditcomposite quality + security reportyesauditor-audit.yml
contributePR(s) to target reponoauditor-contribute.yml
trackoutcome events appended to events.jsonlnoauditor-track.yml
classifycategorical label on a PR commentno (model-deterministic)auditor-classify.yml
refinerule-edit PR (human-gated)no (LLM-generated, human-merged)auditor-refine-rules.yml
citecitation-edit PR (human-gated)noauditor-cite-exemplars.yml, propose-rule-citations.py
difffinding-by-finding comparisonnodiff-findings.py, auditor-docs-diff.yml
reportrolled-up summary at a cadencenoauditor-daily-report.yml, generate-daily-report.py
reviewrule-review issue body (human reads, decides)yes (human)auditor-rule-review.yml, generate-rule-review-body.py
proposea draft for human approvalnopropose-rule-citations.py
validateyes/no on a structural rulenovalidate-feedback.sh, validate-rule-ids.py

Sibling-granularity note (P1): report is broader than its peers (classify, refine, cite, diff). The auditor's noun-named workflow convention absorbs this — workflows that produce reports are noun-named after the output (auditor-daily-report, auditor-rule-review), and the verb report is the generic act behind that family. Documented inconsistency, not a P1 violation; flagged here so future additions don't replicate the pattern without intent.

Cross-scope homonyms (same meaning in both scopes):

  • scan — pattern-match against a signature database (used by security-scan command and scan-suppressions.py)
  • test — pass/fail against named specs (used by /nlpm:test and auditor-integration-test.yml)
  • discover — produce a candidate list (/nlpm:ls description text and auditor-discover.yml)
Verbs proposed but not entered

Per the precedence order in analysis/vocabulary-design-principles.md (P6 last; warrant is an entry check, not a veto), proposed terms split into two lists.

Deferred (P2–P5 satisfied; awaiting warrant):

Proposed verbClosure gap or judgment namedWarrant needed
triageFinding-disposition (P4 closure: finding has no consumer verb)User warrant — practitioner reaches for the term unprompted
review (internal scope)Human-in-the-loop reading, sanctioned cross-scope homonym with auditor reviewUser warrant — practitioner names a review act in internal artifacts
rationalizeVocabulary curation (P5: act of picking canonical from extracted frequencies has no name)User warrant — practitioner names the curation act

Deferred terms are documented but not yet canonical. R51 does not flag them as deprecated — they are nameless gaps, not synonyms.

Rejected by higher principle (no entry possible regardless of warrant):

Proposed verbBlocking principleReason
audit (internal scope)P1Merge test fails — score+check already cover internal-scope evaluation
lint (internal scope)P1Synonym of check; same identity criterion
validate (internal scope)P1Collapses to check in internal scope (canonical in auditor scope)
analyze (internal scope)P1Synonym of score; quantitative evaluation

Nouns

Artifact-class nouns (rigid; survive state changes)
Canonical nounWhat it isExamples
artifactany NL programming file Claude Code consumesumbrella term
commandcommands/*.md, invoked via /<plugin>:<command>commands/score.md
agentagents/*.md, invoked via Task tool with subagent_typeagents/scorer.md
skillskills/<plugin>/<name>/SKILL.md, auto-loaded by description matchskills/nlpm/rules/SKILL.md
rulea numbered item (R01–R50) inside the rules skillinside skills/nlpm/rules/SKILL.md
hookshell script wired via hooks.jsonhooks/hooks.json
manifestplugin.json or marketplace.json.claude-plugin/plugin.json
frontmatterYAML block delimited by --- at the top of a Markdown fileevery command, agent, skill

Sanctioned homonyms (distinct senses, not drift — the drift scanner should not cluster these against the canonical nouns above):

TermSanctioned senseWhere
componenta structural part of the scored project's codebase — code modules, directories, services; may not be NL artifacts at allR35/R49 rule text ("component map"), skills/nlpm/scoring/SKILL.md R35 row
issuea GitHub issue — the platform object the auditor opens, tracks, and closesauditor scope: workflows, auditor-rule-review.yml, auditor pipeline prose in docs/auditor.md

Everywhere else, component naming plugin pieces (command/agent/skill/hook) and issue naming a detected problem are drift: the canonical nouns are artifact and finding.

Implementation-role nouns (P2/P3 — agent names ride alongside command verbs)
Role-nounPaired verbFile
scannerlsagents/scanner.md
scorerscoreagents/scorer.md
checkercheckagents/checker.md
testertestagents/tester.md
vague-scannerscore (sub-step)agents/vague-scanner.md
security-scannerscanagents/security-scanner.md

These are not top-level verbs in their own right (P3). They are role-names for sub-step agents. Treat them as nouns naming the worker, not as operations on artifacts.

Show full SKILL.md (713 more words)Show less
Output-class nouns (produced by verbs)
NounProduced byNotes
scorescore verbnumber 0–100 + penalty breakdown
findingscore, check, scanone problem detected; carries a fingerprint in auditor scope
violationchecka finding specifically from cross-reference checking
penaltyscorethe points subtracted by a single finding
snapshotscore, trenda point-in-time record appended to .claude/nlpm-history.json
inventorylsthe list of artifacts discovered in a path
reportaudit, report, trenda roll-up document
spectesta .nlpm-test/*.spec.md file defining expected behavior
Auditor-scope nouns (only meaningful inside auditor/)
NounWhat it isFile evidence
case-studypost-merge article comparing original audit to HEADauditor/audits/<slug>.re-audit.md
exemplarteaching artifact from a high-scoring auditauditor/exemplars/<slug>.md
fingerprintcontent-hash identity of a finding across re-runscompute-fingerprint.sh
eventone append-only record in events.jsonlauditor/logs/events.jsonl
disagreementself/maintainer dispute over a findingauditor/disagreements.jsonl
registrythe tracked-repo databaseauditor/registry/repos.json
dispositiona finding's lifecycle statusenum values inside events.jsonl
policy gatea pre-PR check (no-external-PRs, CLA, pushback)auditor-contribute.yml

The bright-line table (P1, P5)

When the evaluation cluster overlaps in practice, use this table to disambiguate:

VerbScopeDeterministic?Judgment?OutputUse when
scoreinternalyesnonumber + penalty listquantifying quality with a rubric
checkinternalyesnoviolation listverifying cross-references and structural consistency
testbothyesnopass/failcomparing actual behavior against a named spec
scanbothyesnofindings against signaturespattern-matching for a known class of problems
auditauditorpartlyyescomposite reportfull quality assessment that combines score + scan + judgment
reviewauditornoyes (human)comment traila human reads and forms an opinion

Two verbs share a scope and an identity criterion ⇒ one must be retired or scope-split. Two verbs share an identity criterion across scopes ⇒ that is a sanctioned homonym (declare it in this table).


How to extend this registry

  1. Add a term only if it has warrant. The four warrant types come from analysis/vocabulary-design-principles.md P6: literary, user, structural, domain. Literary warrant is automatic via the extraction script — if the script picks the term up, it qualifies.
  2. Re-run the extraction script. python3 analysis/scripts/extract-vocabulary.py writes analysis/vocabulary-extract/summary.md. New terms appear there.
  3. Slot the term. Add a row to the right table above (internal verb / auditor verb / artifact-class noun / role-noun / output-class noun / auditor-scope noun).
  4. Cite the file evidence. Every row has an "examples" or "file evidence" column. Cite at least one path.
  5. If retiring a synonym, list it under its canonical verb's "deprecated synonyms" line. Do not silently drop terms; deprecation is itself a vocabulary act and needs to be visible.

Deferred work (documented, not yet executed)

ItemWhy deferredWhat unblocks it
Per-rule warrant tags on R01–R50Requires reading every rule + judging which warrant it earns its place by. User warrant data lives in rule-health.py outputs.A separate auditor-refine-rules follow-up pass that combines rule-health data with this principle set.
Adding triage as a /nlpm:triage commandP4 closure gap is real but triage has zero literary warrant today. User warrant is the missing evidence.A practitioner reaching for the word unprompted in actual NLPM use.
Resolving the agent-name-vs-command-name shadowing (scanner/ls, scorer/score)Already documented above as a class boundary; no rename proposed.A confirmed case of practitioner confusion. None observed today.
(resolved 2026-05-19) Workflow filename conventionDeclared as sanctioned split. See "Auditor workflow filename convention" below.—

Auditor workflow filename convention

.github/workflows/auditor-*.yml filenames follow a two-rule split, both sanctioned:

PatternUse whenExamples
auditor-<verb>The workflow changes state (gates a transition, opens a PR, classifies, moves a finding through its lifecycle)auditor-audit.yml, auditor-contribute.yml, auditor-track.yml, auditor-classify.yml, auditor-refine-rules.yml, auditor-cite-exemplars.yml, auditor-discover.yml
auditor-<output-noun>The workflow's purpose is to produce a named artifact that downstream tooling consumes by nameauditor-case-study.yml, auditor-exemplar.yml, auditor-daily-report.yml, auditor-suppressions.yml, auditor-docs-diff.yml, auditor-rule-review.yml

By P3, both patterns produce or gate, so both pass the top-level-verb test. The split is genuine: noun-named workflows are named after what they write, verb-named workflows after what they do.

Outlier: auditor-batch-processor.yml is named after a process role, not a verb or an output noun. Rename candidate: auditor-promote-batch. Deferred — git history, badge, and external references make the rename costly, and the existing name has literary warrant.


Scope note

This skill loads on requests to write, review, or name NLPM artifacts. For framework-level facts (hook event names, manifest field schemas, Claude Code naming conventions), see [[conventions]]. For the 50 quality rules (R01–R50), see [[rules]]. For penalty tables, see [[scoring]].

© xiaolai, ISC. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in skills/nlpm/vocabulary of xiaolai/nlpm.

  • SKILL.md
  • registry.yaml

Open the folder on GitHubat commit bfa2fc2

Compare with similar skills

Vocabulary next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Vocabulary compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Vocabulary this skillxiaolai/nlpm150—~3.9kAutomated safety check: PassISC
MCP Server Builderanthropics/skills180k63 repos~2.3kAutomated safety check: PassApache-2.0
Hook Development for Claude Code Pluginsanthropics/claude-plugins-official38k10 repos~4.1kAutomated safety check: NotesApache-2.0
Using Superpowersfarm-fe/farm5.6k36 repos~1.4kAutomated safety check: PassMIT
Executing Plans Inlineobra/superpowers297k2 repos~5.1kAutomated safety check: PassMIT
Skill CreatorAzure/azqr79689 repos~8.2kAutomated safety check: PassApache-2.0

Similar skills

  • MCP Server Builder

    anthropics/skills

    Official

    Guides the design and implementation of Model Context Protocol servers in TypeScript or Python, from tool naming and error messages to evaluation.

    180k GitHub starsUsed in 63 repos~2.3k tokens
    Agent WorkflowsAuto-check passed
  • Hook Development for Claude Code Plugins

    anthropics/claude-plugins-official

    Official

    Explains how to write Claude Code plugin hooks, both prompt-based checks and bash commands, for events such as PreToolUse, Stop and SessionStart.

    38k GitHub starsUsed in 10 repos~4.1k tokens
    Agent WorkflowsAuto-check: notes
  • Using Superpowers

    farm-fe/farm

    A skill your agent uses when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions

    5.6k GitHub starsUsed in 36 repos~1.4k tokens
    Agent WorkflowsAuto-check passed
  • Executing Plans Inline

    obra/superpowers

    Has the agent carry out an implementation plan itself, task by task in the current session, keeping a ledger, proving each step with a test and ending with one whole-branch review.

    297k GitHub starsUsed in 2 repos~5.1k tokens
    Agent WorkflowsAuto-check passed
  • Skill Creator

    Azure/azqr

    Official

    Create new skills, modify and improve existing skills, and measure skill performance.

    796 GitHub starsUsed in 89 repos~8.2k tokens
    Agent WorkflowsAuto-check passed
  • Claude Code Agent Development

    anthropics/claude-plugins-official

    Official

    Explains how to write agents for Claude Code plugins: the markdown file with YAML frontmatter, trigger descriptions, model and color settings, and system prompt design.

    38k GitHub starsUsed in 7 repos~2.8k tokens
    Agent WorkflowsAuto-check passed

More from xiaolai/nlpm

All 15 skills in this repo
  • Conventions

    xiaolai/nlpm

    Universal NL conventions: SKILL.md open spec, AGENTS.md, vague quantifiers, naming.

    150 GitHub stars~3.6k tokensUpdated today
    Auto-check passed
  • Antigravity and Gemini CLI artifact schemas: .gemini/ paths, extensions, hooks.

    150 GitHub stars~3.1k tokensUpdated today
    Auto-check passed
  • Conventions Codex

    xiaolai/nlpm

    Codex CLI artifact schemas: config.toml, .codex-plugin, skills, hooks, AGENTS.md.

    150 GitHub stars~4.9k tokensUpdated today
    Auto-check passed
  • Orchestration

    xiaolai/nlpm

    Multi-agent workflow patterns: parallel dispatch, pipelines, QC gates, retries.

    150 GitHub stars~3k tokensUpdated today
    Auto-check passed
  • Patterns

    xiaolai/nlpm

    NL artifact anti-patterns: vague quantifiers, bare prohibitions, oversized skills.

    150 GitHub stars~3.9k tokensUpdated today
    Auto-check passed
  • Scoring

    xiaolai/nlpm

    100-point NL artifact rubric: penalty tables per artifact type, calibration cases.

    150 GitHub stars~5.3k tokensUpdated today
    Auto-check passed

Categories

Questions about Vocabulary

What does Vocabulary do?

NLPM noun/verb registry (R51): pick the canonical term, detect vocabulary drift. Vocabulary is an agent skill from xiaolai/nlpm. NLPM noun/verb registry (R51): pick the canonical term, detect vocabulary drift.

When should I use Vocabulary?

Vocabulary fits situations like: agent Workflows work in your project.

How do I install Vocabulary in Claude Code?

Run `npx skills add xiaolai/nlpm --skill vocabulary -a claude-code`. Or copy the skill folder (skills/nlpm/vocabulary in xiaolai/nlpm) into .claude/skills/vocabulary in your project. Claude Code loads it when a task matches its description.

How do I install Vocabulary in Codex?

Run `npx skills add xiaolai/nlpm --skill vocabulary -a codex`. Or copy the skill folder (skills/nlpm/vocabulary in xiaolai/nlpm) into .agents/skills/vocabulary in your project. Codex loads it when a task matches its description.

Can I use Vocabulary in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add xiaolai/nlpm --skill vocabulary -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/vocabulary, .gemini/skills/vocabulary, .github/skills/vocabulary and .opencode/skills/vocabulary in your project.

What does Vocabulary need to run?

Going by SKILL.md and its folder, Vocabulary needs the command-line tools its instructions call (python3).

Does Vocabulary access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Vocabulary safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Vocabulary use?

Vocabulary is published under the ISC licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Vocabulary use?

About 3.9k tokens (SKILL.md is roughly 16k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Vocabulary?

Skills that share tags, products or a category with Vocabulary: MCP Server Builder (anthropics/skills, 180k stars), Hook Development for Claude Code Plugins (anthropics/claude-plugins-official, 38k stars), Using Superpowers (farm-fe/farm, 5.6k stars) and Executing Plans Inline (obra/superpowers, 297k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Vocabulary?

xiaolai (a GitHub user) maintains it in xiaolai/nlpm, which has 150 GitHub stars. The repository holds 15 skills in this directory. The repository was last updated on October 10, 2026.

Source: xiaolai/nlpm on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.