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:
-
Tier 1 — Routing & Discovery Metadata (~50–100 words / $\le 150$ tokens):
- Fields:
name(1–64 characters) anddescription(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.
- Fields:
-
Tier 2 — Skill Instructions & Body (< 5,000 tokens / < 500 lines):
- Scope: The main
SKILL.mdbody (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.
- Scope: The main
-
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 anindex.mdbundle map for progressive disclosure.scripts/: Executable helper tools and automation scripts.assets/: Static templates, seed data, or boilerplate files.
- Scope: Subdirectories loaded only when explicitly requested by instructions:
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
homepageandrepositoryfields in frontmatter when a single canonical URL suffices. This reduces metadata overhead by ~60–80 tokens per skill while maintaining full provenance.
- Single Canonical URL Standard: Avoid duplicating
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.jsonorclaude_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
namein