Skip to content

Skills (Camada 10)

684 SKILL.md files across 39 area folders, with 127 curated entries in 4 tiers.

Loader

SkillLoader walks <area>/.agents/skills/**/SKILL.md, parses YAML frontmatter, and returns SkillManifest records.

from src.skills import SkillLoader

loader = SkillLoader(root_dir=".")
skills = loader.load_all()         # 684 manifests
m = skills["agent-evaluation"]
print(m.area, m.description[:80])

Nested skills (e.g. gsd/agents/debugger) are loaded too. When a folder-name collision occurs, the second skill is given a path-derived ID.

Router

SkillRouter matches an intent string against skill descriptions + names + sub_areas using word-overlap (Jaccard) similarity. Tier bias breaks ties in favor of platinum > gold > silver > bronze.

from src.skills import SkillRouter, RoutingRequest

router = SkillRouter(loader=loader)
matches = router.route(RoutingRequest(
    intent_text="build a react chart component",
    area_hint="frontend",            # optional
    min_similarity=0.10,
    top_k=5,
))
for m in matches:
    print(f"{m.score:.4f}  {m.skill.skill_id}  ({m.reason})")

For v1.5+ this swaps to embedding-based similarity without changing the API.

Invoker

SkillInvoker glues a skill manifest to the runtime:

  1. Read SKILL.md instructions
  2. Build prompt = instructions + inputs
  3. Call ModelManager.call(prompt, tier=…) (with CircuitBreaker via per-skill breaker)
  4. Emit AgentMetrics event
  5. Return SkillResult with output, tokens, cost, duration
from src.skills import SkillInvoker
from src.ai import AgentMetrics, ModelManager

invoker = SkillInvoker(
    model_manager=ModelManager.default(),
    metrics=AgentMetrics(),
)
result = invoker.invoke(
    skill=matches[0].skill,
    agent_id="cortex",
    inputs={"task": "render bar chart"},
    tier="standard",
)

Versioning

SkillVersioning reads docs/reference/registries/DEPRECATED-SKILLS-REGISTRY.yaml. Each skill has one of three states:

  • ACTIVE — default
  • DEPRECATED — still callable, but allow() returns a warning pointing to the successor
  • SUNSET — allow() returns False; the invoker refuses the call
from src.skills import SkillVersioning

v = SkillVersioning()
allowed, warning = v.allow("some-old-skill")
if warning:
    print(warning)   # "deprecated:prefer:new-skill-id"

Tier model

Tier Threshold Count Notes
Platinum ≥100K installs OR official 34 Top-of-mind, manually curated
Gold 10K-100K 30 High-confidence community + official
Silver 1K-10K (provenance validated) 33 Owner/package match enforced
Bronze 100-1K (provenance validated) 30 Same scoring as silver
Experimental <100 not curated —

The curated registry (docs/reference/registries/_skills-registry.yaml) carries last_verified, quality_score, status, source_org, and sub_areas for every entry. The _meta block is auto-synced by scripts/sync_registry.py.

Adding a skill

  1. Install via marketplace: npx skills add <owner/repo@skill> -y
  2. Relocate from default .agents/skills/<name>/ to the right area: <area>/.agents/skills/<name>/
  3. (Optional) Add a curated entry under platinum/gold/silver/bronze in _skills-registry.yaml
  4. python scripts/sync_registry.py to refresh _meta
  5. python scripts/gen_registry_full.py to refresh registry-full.yaml
  6. make audit-quick to confirm structural + semantic gates pass