Files

Defame1297 83277f4e5c feat(kyberforge): ground skill-audit qualitative rubric in agentskillsio spec

Add references/description-quality.md and references/body-discipline.md to
skill-audit — condensed, rubric-focused extracts from the agentskills.io
specification docs. Both files are loaded conditionally via progressive
disclosure triggers added to Step 3 (Description and Body discipline
dimensions), so the agent consults the spec source when a finding is
borderline rather than relying solely on inline heuristics developed
during the skill-write authoring cycle.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-22 19:53:45 +00:00

2.5 KiB

Raw Blame History

Description Quality Reference

Source: agentskills.io — optimizing-descriptions

How triggering works

At startup, agents load only the name and description of each skill. When a user's task matches a description, the agent reads the full SKILL.md into context. The description carries the entire triggering burden — the body is never seen until after triggering.

Agents typically consult skills only for tasks requiring knowledge beyond their defaults. Specialized knowledge — unfamiliar APIs, domain-specific workflows, uncommon formats — is where description wording makes the difference.

What a good description does

Imperative phrasing — "Use when..." not "This skill does...". The agent is deciding whether to act.
User intent, not mechanics — describe what the user is trying to achieve, not how the skill works internally.
Err toward being pushy — explicitly name contexts where the skill applies, including cases where the user doesn't name the domain: "even if they don't mention X explicitly."
Specificity over vagueness — "parses and validates OpenAPI specs" beats "helps with APIs."
Near-miss exclusions — add "Do not use when..." only if a near-miss skill exists that could steal activations. Use strong near-misses (queries that share keywords but need something different), not weak ones ("write a fibonacci function").
Hard limit: 1024 characters — descriptions grow during revision; check length before finalising.

Before / after

# Weak
description: Process CSV files.

# Strong
description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use when
  the user has a CSV, TSV, or Excel file and wants to explore, transform,
  or visualize the data, even if they don't explicitly mention "CSV" or
  "analysis."

The strong version names capabilities precisely and broadens applicability beyond explicit keyword matches.

Auditing guidance

Flag as FAIL if:

Phrasing is descriptive ("This skill...") not imperative ("Use when...")
Capabilities are vague ("helps with APIs") — require precise verbs and nouns
No indirect trigger coverage when indirect cases clearly exist
No near-miss exclusions when a sibling skill could plausibly steal activations
Length exceeds 1024 characters

Flag as SUGGESTION if:

Indirect trigger coverage exists but could be more specific
Near-miss exclusions are present but target weak near-misses only

2.5 KiB Raw Blame History