skillpack/verify/
schema.rs

1//! The Claude Code schema constants that `verify` enforces.
2//!
3//! Every literal here is grounded in the public docs (code.claude.com/docs/en/
4//! plugins-reference, plugin-marketplaces, skills) as checked against the live
5//! spec. Keep a comment citing the source for each rule so future-me can
6//! re-verify against an updated spec without guessing where a number came from.
7
8/// The combined `description` + `when_to_use` text in the SKILL.md skill
9/// listing is capped at 1,536 characters.
10///
11/// Source: code.claude.com/docs/en/skills — "the combined `description` and
12/// `when_to_use` text is truncated at 1,536 characters in the skill listing."
13pub const SKILL_LISTING_CHAR_CAP: usize = 1_536;
14
15/// A skill `name` is capped at 64 characters.
16///
17/// Source: skill-authoring docs — "name: Maximum 64 characters."
18pub const SKILL_NAME_MAX_CHARS: usize = 64;
19
20// `when_to_use` advertises trigger phrases; we flag if it's present but empty
21// or only whitespace, since that defeats the whole point of the field.
22// (We do not enforce a hard length — the listing cap covers the upper bound.)
23
24/// Plugin / marketplace `name` must be kebab-case and contain no spaces.
25/// Source: plugin-marketplaces — "kebab-case, no spaces." We use a permissive
26/// regex that matches the AgentSkills.io open standard `^[a-z][a-z0-9-]*[a-z0-9]$`,
27/// which allows no consecutive hyphens and a trailing alnum.
28pub const NAME_KEBAB_REGEX: &str = r"^[a-z][a-z0-9-]*[a-z0-9]$";
29
30// A name that is a single lowercase letter is a degenerate corner not covered
31// by the regex above (which requires ≥2 chars); we accept it explicitly below
32// by treating length-1 names as valid iff they're `[a-z]`.
33
34// The relative-path form of a marketplace plugin `source` MUST start with
35// `./`. We only flag structural problems; absolute and `../` are flagged.
36// Source: plugin-marketplaces — "Relative path ... Must start with `./`.
37// Resolved relative to the marketplace root."
38
39/// Names we refuse outright. The design doc listed a candidate set; the live
40/// docs did not confirm Anthropic publishes an authoritative reserved list, so
41/// these are treated as WARNINGS (not hard failures), per the honest-verifier
42/// posture in design §13 Mitigation ("verify is deliberately conservative").
43/// A maintainer can ignore a warning; they cannot ignore the reputation cost of
44/// clobbering an Anthropic-owned name.
45pub const RESERVED_NAMES: &[&str] = &[
46    "claude-code-marketplace",
47    "claude-code-plugins",
48    "claude-plugins-official",
49    "anthropic-marketplace",
50    "anthropic-plugins",
51    "anthropic",
52    "claude",
53    "agent-skills",
54    "skills",
55    "official",
56];
57
58/// `plugin.json` MUST live at `.claude-plugin/plugin.json`. Source:
59/// anthropics/claude-code manifest-reference.md — "Required path:
60/// `.claude-plugin/plugin.json`."
61pub const PLUGIN_JSON_PATH: &str = ".claude-plugin/plugin.json";
62/// The `.claude-plugin/` directory houses the marketplace + plugin manifests.
63/// Source: anthropics/claude-code plugin-reference.md. Verified July 2026.
64pub const CLAUDE_PLUGIN_DIR: &str = ".claude-plugin";
65
66/// `marketplace.json` lives at `.claude-plugin/marketplace.json`. Source:
67/// plugin-marketplaces — "Create `.claude-plugin/marketplace.json`."
68pub const MARKETPLACE_JSON_PATH: &str = ".claude-plugin/marketplace.json";
69/// Cursor project rules live under `.cursor/rules/<name>.mdc`. Source:
70/// cursor.com/docs/rules — "Project rules are stored as `.mdc` files in
71/// `.cursor/rules/`." Verified July 2026.
72pub const CURSOR_RULES_DIR: &str = ".cursor/rules";
73/// Codex CLI skills live under `.codex/skills/<name>/SKILL.md`. Source:
74/// the AgentSkills open standard (agskills.dev) and the Codex CLI skill
75/// convention — same `SKILL.md` frontmatter shape as Claude, installed under
76/// `.codex/skills/`. Verified July 2026.
77pub const CODEX_SKILLS_DIR: &str = ".codex/skills";
78/// OpenCode agent definitions live under `.opencode/agents/<name>.md`. Source:
79/// opencode.ai/docs/agents — "Place them in: Per-project:
80/// `.opencode/agents/`". The markdown file name becomes the agent name.
81/// Frontmatter: `description` (required), `mode`/`temperature`/`permissions`
82/// (optional). Verified July 2026.
83pub const OPENCODE_AGENTS_DIR: &str = ".opencode/agents";
84
85/// GitHub Copilot custom instructions live at
86/// `.github/copilot-instructions.md`. Source:
87/// docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/
88/// add-repository-instructions — "The path is always
89/// `.github/copilot-instructions.md`." Plain markdown, no frontmatter.
90/// Verified July 2026.
91pub const COPILOT_INSTRUCTIONS_PATH: &str = ".github/copilot-instructions.md";
92
93// Action-verb heuristic: the first word of a good skill description is an
94// action verb (e.g. "Lint", "Generate", "Format"). We don't enforce grammar —
95// we only flag descriptions that don't begin with an alphabetic word, a
96// strong signal the description was written as a name/title. Source: skill
97// best-practices — open with "one sentence describing what the skill does";
98// the listing places the key use case first.
skillpack/verify/schema.rs

skillpack/verify/
schema.rs
