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

skill-optimizer

Comprehensive guide to develop and improve Agent Skill performance. Contains best practices for skill formatting (frontmatter and metadata), naming, descriptions, fine-tuning activation triggers, evaluations, production-readiness and open sourcing. Activate when developing new skills or refining existing ones.

danicat · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add danicat/skills --skill skill-optimizer

技能说明


name: skill-optimizer description: > Comprehensive guide to develop and improve Agent Skill performance. Contains best practices for skill formatting (frontmatter and metadata), naming, descriptions, fine-tuning activation triggers, evaluations, production-readiness and open sourcing. Activate when developing new skills or refining existing ones. license: Apache-2.0 metadata: category: agents tags: "skills, agent-skills, optimization, standards" author: Daniela Petruzalek (daniela@danicat.dev) version: "0.5.0" catalog: https://skills.danicat.dev

Agent Skill Optimizer

Procedures, authoring principles, and quality standards for creating, auditing, and optimizing Agent Skills according to the Agent Skills specification and open-source best practices.

Available scripts

  • scripts/count_tokens.py — Audits skills and categories against Tier 1, 2, and 3 token limits using Vertex AI ADC, Gemini API, or offline heuristic.

Skill Architecture & Progressive Disclosure Limits

Skills use a 3-tier progressive disclosure model to minimize token consumption:

  1. Tier 1 — Routing & Discovery Metadata (~50–100 words / $\le 150$ tokens):

    • Fields: name (1–64 characters) and description (1–1024 characters).
    • Runtime behavior: Injected into the model's system prompt at startup for all available skills so the orchestrator can route tasks accurately.
    • Budget limit: Keep routing tokens $\le 150$ (ideal ~100 tokens). Keep description $\le 1024$ characters.
  2. Tier 2 — Skill Instructions & Body (< 5,000 tokens / < 500 lines):

    • Scope: The main SKILL.md body (excluding frontmatter).
    • Runtime behavior: Loaded into active context only when the skill is explicitly activated.
    • Budget limit: Strict limit of $\le 5,000$ tokens and $\le 500$ lines. Move detailed API tables, expansive guides, and catalogs into Tier 3.
  3. Tier 3 — On-Demand Resources & References:

    • Scope: Subdirectories loaded only when explicitly requested by instructions:
      • references/: Domain guides, schemas, cheat sheets, and syntax rules. Formatted as Open Knowledge Format (OKF v0.2) concept markdown documents with YAML frontmatter (type, resource, sources, verified) and an index.md bundle map for progressive disclosure.
      • scripts/: Executable helper tools and automation scripts.
      • assets/: Static templates, seed data, or boilerplate files.

Frontmatter Specification & Metadata Guidelines

Every skill must provide valid YAML frontmatter containing core identifiers, licensing, and an authoritative canonical URL:

---
name: my-skill
description: >
  Concise definition of the skill and tangible topics covered. Mentions key
  architecture or superpower. Activate when encountering primary use case or
  problem conditions.
license: Apache-2.0
metadata:
  category: coding
  tags: "go, refactoring, testing, quality"
  author: Maintainer Name (maintainer@example.com)
  version: "1.0.0"
  canonical: https://skills.example.com/coding/my-skill/
compatibility: Requires Go 1.22+
allowed-tools: Bash(go:*) Read
---

Field Rules & Single-URL Provenance

1. Core Top-Level Fields

  • name (required): 1-64 characters, lowercase alphanumeric and single hyphens (a-z, 0-9, -). No consecutive hyphens (--), no leading/trailing hyphens. Must match directory name exactly.
  • description (required): 1-1024 characters. Non-empty. Follows the 3-Part Skill Description Blueprint (Definition & Scope + Superpower + Human Triggers). Do not include internal implementation plumbing.
  • license (required): Short SPDX license identifier (e.g., Apache-2.0, MIT) or path to a bundled license.
  • compatibility (optional): Environment or tool requirements (e.g., Requires Python 3.11+). Omit if standard.
  • allowed-tools (optional): Space-separated list of pre-approved tools (experimental).

2. Metadata Block (metadata)

  • category (recommended): Functional taxonomy domain (e.g., coding, agents, devops, media, writing, analytics). Recommended to match the parent category folder name in structured repositories.
  • tags (recommended): 3 to 6 high-level domain anchors for search and categorization. Avoid redundant synonym stuffing.
  • author (recommended): Maintainer attribution string (e.g., Author Name (email@example.com) or organization name).
  • version (recommended): Semantic Versioning SemVer 2.0.0 (MAJOR.MINOR.PATCH).
  • canonical (recommended): The authoritative web URL pointing to the skill's published documentation (e.g., https://skills.example.com/<category>/<skill-name>/).
    • Single Canonical URL Standard: Avoid duplicating homepage and repository fields in frontmatter when a single canonical URL suffices. This reduces metadata overhead by ~60–80 tokens per skill while maintaining full provenance.

3. Zero Contamination Gate

All public skills must be strictly generic, modular, and platform-agnostic:

  • No local machine specifics: Never include personal machine paths or local home directory structures.
  • No internal corporate knowledge: Never include internal project names, private channel names, or proprietary infrastructure URLs.
  • No credentials or tokens: Never leak API keys, personal access tokens, or private secrets.

Optional Reference: Agent Skills MCP Server

To query live specifications and documentation during development, you can connect the Agent Skills MCP server:

  • Server URL: https://agentskills.io/mcp
  • MCP Configuration (e.g., ~/.gemini/config/mcp_config.json or claude_desktop_config.json):
{
  "mcpServers": {
    "agentskills": {
      "url": "https://agentskills.io/mcp"
    }
  }
}

5-Stage Skill Audit & Optimization Process

Follow this procedure when creating, reviewing, or refining skills:

Stage 1: Structure & File Layout

  • Name Alignment: Confirm name in
阅读完整来源 ↗