skill-maintainer
Standards and release operations for the vegafactory repository itself. Use when working on this repository - editing an existing skill (SKILL.md, references, scripts, tests), renaming, deprecating, or removing a skill, creating or checking a skill group, cutting a release or rolling one back, or checking cross-harness portability across Claude Code, Codex and the agentskills.io standard. Not for scaffolding a new skill or scoring one against the contract (skillify), and not for skills that live in other projects.
- License 许可
- MIT
- 最近更新
- 2026-09-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- skill-maintainer
- description
- Standards and release operations for the vegafactory repository itself. Use when working on this repository - editing an existing skill (SKILL.md, references, scripts, tests), renaming, deprecating, or removing a skill, creating or checking a skill group, cutting a release or rolling one back, or checking cross-harness portability across Claude Code, Codex and the agentskills.io standard. Not for scaffolding a new skill or scoring one against the contract (skillify), and not for skills that live in other projects.
02 资源文件 5
- 参考文档agents/openai.yaml288 B
- 参考文档evals/evals.json2.9 KB
- 参考文档references/release-ops.md5.5 KB
- 参考文档references/standards.md8.0 KB
- 参考文档tests/fixtures/trigger-queries.json1.3 KB
03 SKILL.md 正文
VegaStack Skill Maintainer
This skill states what must be true; skillify states how to get there. When a rule here disagrees with CONTRIBUTING.md or .vegastack/dev.md, those win — then fix this skill.
Operating rules
- Skill content lives only in the skill's own directory, at exactly two depths:
skills/<name>/orskills/<group>/<name>/; deeper is a build error. A group is a directory of skills plus aGROUP.md(title, then a blurb line); group and skill names share one namespace and grammar. Wiring lives outside the skill — thepackages/cli/packaging.jsonallowlist, keyed by bare skill name because the bundle is flat and an install carries no group; the root README row; the changeset (a.changeset/<slug>.mdfile whose frontmatter names the package and bump, shaped per dev-implement's changelog rule; changesets are compiled intopackages/cli/CHANGELOG.mdat release) — and the skillify scaffolder writes all three. "The operator" throughout is the human running the workflow, named by their GitHub username. - Frontmatter is exactly
nameanddescription; the spec'slicense,compatibility, andmetadataare a policy exception needing maintainer sign-off. nameequals the directory name: a lowercase letter first, then[a-z0-9-], no leading, trailing, or consecutive hyphens, at most 64 chars.description: at most 1024 chars, third person, no angle brackets, no space-hash. It states what the skill does and when to load it as a calm "Use when …" conditional carrying the concrete phrasings users type, plus one "Not for …" clause naming the nearest neighbour, because harnesses quote descriptions verbatim in the skill list and emphatic wording (all-caps "must", "critical", "load this before") over-triggers there. Triggers go in the first sentence because listings truncate. The description never summarises the workflow: agents follow the summary and skip the body.SKILL.mdunder 500 lines (target 150), roughly 5k tokens; detail inreferences/, executables inscripts/, templates inassets/; relative links stay one level deep inside the skill.- No Claude-only body syntax (token list in standards); reference scripts as plain relative paths from the skill directory.
- A volatile fact (version, mechanism name, limit, dated claim) lives in a references file with its checked date and official source link, and is re-checked against that source when older than 60 days.
- Before finishing any change, from the repo root:
node packages/cli/scripts/validate-skill.mjs <skill-dir>,bun test ./<skill-dir>, andnode packages/cli/scripts/structure.mjs checkmust pass.bun run check:fastincludes the structure check;bun run test:affectedruns the tests the change reaches.
Route progressively
| Need | Read |
|---|---|
| Claude Code and Codex standards: discovery paths, frontmatter, budgets, install surfaces, portability | standards |
| a new skill: the should-it-exist gate, scaffolding, audit, evals | the skillify skill |
| repo shape, groups, the structure check | the group workflow below |
| release, rename, deprecate, rollback | release ops |
| authoritative repo policy | CONTRIBUTING.md and .vegastack/dev.md |
Workflow: create or maintain a group
Groups are this skill's; the tool is packages/cli/scripts/structure.mjs at the repo root.
- Create a group —
node packages/cli/scripts/structure.mjs create-group <name> --title "<Display Title>" --blurb "<one line>"prints the plan and each refusal before anything is written;--writeapplies it. - Put skills in it — skillify's scaffolder places a new skill with
--group <name>, refusing an unknown or malformed group before writing. Moving a skill is agit mvplus its README row and its test's validator-import depth. - Check the shape —
node packages/cli/scripts/structure.mjs checkblocks on depth, name collisions,GROUP.md, README-section, packaging, and README-row faults; it warns on an empty group, a group of one, and placeholder text (--strict: warnings exit 1). Dot-prefixed files are ignored everywhere.
An installed skill is always <surface>/<bare-name>/; a group is a selection: add, verify, and remove take a name, --group <name>, or --all, one transaction per group. packages/cli/repo-only.json marks skill-maintainer and skillify repo-only, so --all skips them; the list is build-validated data, independent of grouping.
Workflow: scaffold a new skill
Run skillify's scripts/scaffold-skill.mjs (--group <name> for a grouped skill), fill in the root README row and changeset placeholders it leaves, and add later packaged files to the packaging entry by hand because the build fails on unlisted files. Then rules 2–6 and 8; the authoring and eval discipline is skillify's.
Workflow: update or maintain
- Content versioning. Per the content-semver bullet in
.vegastack/dev.md: new rules, references, recorded decisions, and skill renames are MINOR; weakening a normative rule, removing a skill, or breaking a per-project profile format is MAJOR (recorded pre-1.0 exception aside); factual refreshes are PATCH. - Date volatile claims. A sentence carrying a vendor version, mechanism name, or numeric budget carries its checked date and official source link; undated volatile facts rot silently.
- Description budgets. Keep triggers in the first sentence: both harness listings truncate, and the limits table below carries the numbers.
- Packaged-file changes. Adding, removing, or renaming a packaged file updates its packaging entry in the same PR.
Workflow: rename, deprecate, or remove
Playbook in release ops: a rename changes the directory and the frontmatter name in the same commit, updates the packaging entry, root README row, changeset, and every cross-reference to the old name (sibling descriptions, fixtures, ambiguous_with entries, docs — grep -rn <old-name> finds them), and is MINOR unless the operator declares MAJOR; deprecation is announced in README and CHANGELOG first; removal deletes the tree, unwires it, and is MAJOR.
Workflow: release
The ## Ship runbook in .vegastack/dev.md is the release sequence and says which steps take the operator's word. One version identity covers the installer and every bundled skill, so a bump leaves every deployed per-project profile valid. Rollback is roll-forward plus npm deprecate. Details: release ops.
Workflow: portability check
- [ ] Frontmatter keys and limits per rules 2–4;
nameequals the directory name. - [ ]
SKILL.mdunder 500 lines; relative links resolve inside the skill; no Claude-only body syntax. - [ ]
agents/openai.yamlpresent for Codex (other harnesses ignore extra files). - [ ] Install surfaces: Claude Code
.claude/skillsor~/.claude/skills; Codex.agents/skillsor~/.agents/skills. - [ ] Rule 8's checks are clean.
Hard limits
| Limit | Value |
|---|---|
name |
≤ 64 chars, lowercase letter first, then [a-z0-9-], no consecutive hyphens, equals directory name |
description |
1–1024 chars, no angle brackets |
SKILL.md |
under 500 lines / ~5k tokens; target under 150 lines |
| Claude Code listing | name + description truncated at 1,536 chars per skill |
| Claude Code body | first 5,000 tokens persist across compaction; 25,000-token shared skills budget |
| Codex skill list | 2% of context window / 8,000 chars — descriptions shortened first |
These mirror marked sentences in standards; update both in one PR when a source changes.
04 同仓库更多 Skills
skills-refresh
Re-verify the dated platform and harness facts the dev skills pin, and file what changed as issues. Use when asked to "refresh the skills", "check the pinned facts", "are our platform facts still true", "run the facts sweep", "what changed in Cloudflare/Next.js/Claude Code since we last checked", when a fact is older than the 60-day window, or when a scheduled refresh run starts. Not for editing skill prose (dev-implement builds the issues this files), authoring or auditing a skill (skillify), or architecture advice from those facts (dev-architect).
beta
fixture
alpha
fixture
beta
fixture
alpha
fixture
alpha
fixture