Files

Defame1297 38f1ba4e03 fix(kyberforge): bridge apm content to Claude Code's flat plugin discovery

Claude Code's (and Copilot's) native plugin installer has zero awareness of
.apm/ nesting -- it convention-scans only flat skills/, agents/, commands/,
hooks.json at each plugin's root. Confirmed via strings on the installed
claude binary and live installs of git@holocron/gitea@holocron/kyberforge@
holocron, all reporting Skills(0) Agents(0) Hooks(0) post ADR-0015's apm
conversion. Root cause (apm_cli/core/plugin_manifest.py): apm's plugin.json
compiler deliberately strips skills/agents/commands keys, assuming the host
already auto-discovers those convention directories -- it has no model of
.apm/ being host-visible at all. Separately, apm's own bundle exporter
(apm_cli/bundle/plugin_exporter.py, behind `apm pack --format plugin`)
implements the correct .apm/ -> flat mapping, but only ever targeted
build/<name>-<version>/, a path nothing in marketplace.json's source: points
at.

scripts/sync-plugin-content.sh wraps that bundle exporter and copies its
agents/, skills/, commands/, instructions/, extensions/, and merged
hooks.json back into each plugin's own root as a second tracked
compiled-output category -- same governance status as
.claude-plugin/plugin.json: generated from .apm/, never hand-edited. tests/
subdirectories are excluded from the mirror (dev fixtures, not host-visible
runtime content; several hardcode a relative repo-root walk-up sized for the
.apm/-nested depth, which breaks when duplicated one level shallower).
Applied for real across all 6 plugins and verified two ways: `claude plugin
validate --strict` passes on every real plugin directory, and a live
`claude --plugin-dir <path> -p "list skills/agents"` behavioral test
confirms content is now actually discovered.

Also, from the same issue #90 review round:
- scripts/check-manifests.sh pointed at each plugin's root-level plugin.json
  (checking skills/hooks/mcpServers/agents pointer fields) -- that file was a
  stale near-duplicate of .claude-plugin/plugin.json nothing else read or
  wrote, now deleted across all 6 plugins. check-manifests.sh is rewritten to
  validate .claude-plugin/plugin.json instead, and drops the pointer-field
  checks entirely (nothing to check -- those fields are correctly absent by
  design). Content-presence drift is now check-plugin-content-sync's job, a
  new pre-push hook wired in .pre-commit-config.yaml.

docs/adr/0017 records the root cause and decision in full, including two
rejected alternatives (patching plugin.json's path fields directly -- apm's
compiler strips them on every run; pointing marketplace.json at apm pack's
build/ output -- a version-suffixed non-source directory nothing can install
from without an extra build step). ADR-0015 and CONTEXT.md are updated to
point at it.

Refs: #90

2026-08-13 16:59:03 +00:00

2.6 KiB

Raw Blame History

source_keys

agentskills-spec

agentskills-optimizing-descriptions

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.6 KiB Raw Blame History