跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

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-creator skill (and plugin-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

TaskRead or RunOutcome
Scaffold a new skillskill-creator (standard skill)Generates the boilerplate; then apply portability discipline from references/frontmatter-reference.md
Modernize an existing skillpython3 scripts/validate_skill.py <skill-dir>Finds contract drift, broken links, stale sources, and missing TOCs
Add runtime-specific metadatareferences/frontmatter-reference.mdScopes extensions to the target runtime instead of treating them as universal
Decide how to split contentreferences/skill-patterns.mdKeeps SKILL.md small and moves detail into references/ or scripts/
Validate behavior, not just syntaxreferences/skill-validation.mdBuilds trigger, non-trigger, and navigation evals
Check Anthropic-specific detailsreferences/anthropic-skills-guide.mdUses Anthropic guidance without treating it as the portable baseline
Ship one skill to multiple runtimes without driftreferences/dual-distribution.mdSingle canonical system prompt + wrapper distributions + drift-check gate
Design router/composable skill flowreferences/skill-patterns.md#pattern-10-stage-based-selection-pipelineSeparates sources, enrichment, filters, scoring, selection, validation, and side effects

Core Contract

Portable baseline:

  • skill-name/SKILL.md is required.
  • name and description are the portable required frontmatter fields.
  • license, compatibility, and metadata are portable optional fields in the open spec.
  • allowed-tools is part of the open spec, but implementation support may vary by runtime.
  • references/, scripts/, assets/, and data/sources.json are 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, and disallowed-tools as 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 (from arguments), ${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 compatibility note 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 a compatibility note naming the target runtime and remove any claim of portability.
  • Even portable-baseline fields carry a nuance worth catching: the open spec requires name and description, 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.yaml as harness-facing config read natively by current Codex CLI (0.149.x), not as part of the portable core — SKILL.md must stay valid without it. Its policy.allow_implicit_invocation: false keeps explicit-only skills out of the per-session skills listing; see references/frontmatter-reference.md §"Repo-Local Codex Notes".
  • Keep SKILL.md description trigger-rich and portable.
  • Keep agents/openai.yaml short_description brief enough for UI surfaces.
  • Keep agents/openai.yaml default_prompt focused 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

  1. Start with 2-3 concrete user tasks and write the evals first.
  2. Draft the portable core: folder name, SKILL.md, name, description, and minimal instructions.
  3. Keep the portable core functional and reference-like unless the runtime explicitly benefits from a richer overlay.
  4. Add runtime-specific metadata only after choosing the target runtime.
  5. Put
阅读完整来源 ↗