agents-skills
Creates and audits agent skills with SKILL.md, references, scripts, and platform-scoped metadata. Use when creating, updating, or validating shared skills.
vasilyu1983 · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add vasilyu1983/AI-Agents-public --skill agents-skills技能说明
name: agents-skills description: Creates and audits agent skills with SKILL.md, references, scripts, and platform-scoped metadata. Use when creating, updating, or validating shared skills. version: "1.1" last_validated: 2026-08-15
Agent Skills
Use this skill to create or modernize skill bundles without conflating the portable core contract with runtime-specific extensions.
Scope — this is a delta on the standard, not a replacement. Generic skill authoring, scaffolding, and eval mechanics are owned by the Agent Skills open spec and the standard
skill-creatorskill (andplugin-dev:skill-development). Use those for boilerplate. This skill owns only the repo-specific delta the standard cannot provide: dual-runtime portability (Claude Code + Codex), catalog/graph gating, and router/composition patterns. Do not replicate the standard here — link to it.
Quick Reference
| Task | Read or Run | Outcome |
|---|---|---|
| Scaffold a new skill | skill-creator (standard skill) | Generates the boilerplate; then apply portability discipline from references/frontmatter-reference.md |
| Modernize an existing skill | python3 scripts/validate_skill.py <skill-dir> | Finds contract drift, broken links, stale sources, and missing TOCs |
| Add runtime-specific metadata | references/frontmatter-reference.md | Scopes extensions to the target runtime instead of treating them as universal |
| Decide how to split content | references/skill-patterns.md | Keeps SKILL.md small and moves detail into references/ or scripts/ |
| Validate behavior, not just syntax | references/skill-validation.md | Builds trigger, non-trigger, and navigation evals |
| Check Anthropic-specific details | references/anthropic-skills-guide.md | Uses Anthropic guidance without treating it as the portable baseline |
| Ship one skill to multiple runtimes without drift | references/dual-distribution.md | Single canonical system prompt + wrapper distributions + drift-check gate |
| Design router/composable skill flow | references/skill-patterns.md#pattern-10-stage-based-selection-pipeline | Separates sources, enrichment, filters, scoring, selection, validation, and side effects |
Core Contract
Portable baseline:
skill-name/SKILL.mdis required.nameanddescriptionare the portable required frontmatter fields.license,compatibility, andmetadataare portable optional fields in the open spec.allowed-toolsis part of the open spec, but implementation support may vary by runtime.references/,scripts/,assets/, anddata/sources.jsonare optional support directories.- Keep the main skill body focused on workflow and navigation; move long detail into support files.
Runtime extensions:
- Treat fields such as
argument-hint,arguments,disable-model-invocation,user-invocable,when_to_use,context,agent,model,effort,hooks,paths,shell, anddisallowed-toolsas runtime-specific until verified in that runtime's current official docs. - In Anthropic runtimes, also verify invocation semantics and substitutions before copying examples:
user-invocable,disable-model-invocation,$ARGUMENTS,$name(fromarguments),${CLAUDE_SESSION_ID},${CLAUDE_EFFORT},${CLAUDE_SKILL_DIR}, and${CLAUDE_PROJECT_DIR}are not portable assumptions. - If you use runtime-specific fields, add a scoped
compatibilitynote naming the target runtime. - A skill that uses runtime-specific headers (
argument-hint,arguments,disable-model-invocation,context,agent,model,effort,hooks,paths,shell,disallowed-tools) is runtime-scoped: add acompatibilitynote naming the target runtime and remove any claim of portability. - Even portable-baseline fields carry a nuance worth catching: the open spec requires
nameanddescription, but Claude Code alone treats every frontmatter field (including those two) as optional and falls back to the directory name for display. Keep setting both explicitly — the portable contract is stricter than any single runtime's tolerance.
Repo-local Codex metadata:
- Treat
agents/openai.yamlas harness-facing config read natively by current Codex CLI (0.149.x), not as part of the portable core —SKILL.mdmust stay valid without it. Itspolicy.allow_implicit_invocation: falsekeeps explicit-only skills out of the per-session skills listing; see references/frontmatter-reference.md §"Repo-Local Codex Notes". - Keep
SKILL.mddescriptiontrigger-rich and portable. - Keep
agents/openai.yamlshort_descriptionbrief enough for UI surfaces. - Keep
agents/openai.yamldefault_promptfocused on when Codex should load the skill. - Revalidate semantic alignment when the skill intent changes; do not require exact string equality between these fields.
Authoring Modes
Shared skills in this repo should default to a functional reference style:
- matter-of-fact
- outcome-oriented
- explicit about inputs, outputs, and navigation
- light on persona, coaching voice, or motivational framing
That is the safest portable baseline across runtimes, especially for Codex-style skill loading.
Some runtimes also benefit from a problem-approach overlay:
- how to think about the task
- ambiguity-handling rules
- coaching or teaching tone
- richer behavioral framing
Use that style only in runtime-specific layers, references, or scoped extensions. Do not let the portable core become a blend of incompatible authoring philosophies.
Workflow
- Start with 2-3 concrete user tasks and write the evals first.
- Draft the portable core: folder name,
SKILL.md,name,description, and minimal instructions. - Keep the portable core functional and reference-like unless the runtime explicitly benefits from a richer overlay.
- Add runtime-specific metadata only after choosing the target runtime.
- Put