​
Skills

Skills are markdown files with YAML frontmatter that define reusable agent behaviors — coding standards, creative workflows, review checklists. The agent reads the description during discovery and pulls in the full body only when a task matches, so skills extend what the agent knows without bloating every prompt.

​
SKILL.md Format

A skill is a directory with a SKILL.md file — frontmatter followed by markdown instructions:

​
Registration Lifecycle

  1. Author — write SKILL.md in a skill directory (e.g. scripts/skills/<slug>/SKILL.md)
  2. Publish — run pnpm exec tsx scripts/skills/publish-skill.ts <slug> which POSTs to StackNet’s /v1/skills endpoint. The server computes a LODE fingerprint, deducts registration cost (1000× multiplier), publishes a skill/<name> rack repo, and pins to IPFS.
  3. Discover — the rack surfaces the skill in /studio/skills and HQ’s SkillsLibrary. The is_public flag is flipped to true on publish so the network can discover it.
  4. Track — each invocation fires a POST /skills/:id/usage increment (best-effort, fire-and-forget) so usage_count reflects real activity.

​
Discovery Scopes

Skills are discovered in priority order — higher scope wins on name collision: Geoff Code scans local directories; the Studio and HQ UIs browse rack-published skills. See Geoff Code Skills for the local file layout.

​
Invocation Patterns

  • Slash command — /skill:<name> in Geoff Code, optionally followed by instructions
  • Automatic — the agent activates a skill when a task matches its description
  • Studio Flow — add skills to a cart at /studio/skills, then “Use in studio” opens a chat seeded with all selected skills
  • MCP — skills_invoke with a skill ID and input text; see MCP Tools Reference
  • @-mention — in Geoff chat, @blueprint-lyrics resolves to the skill via the SKILL_IDS registry in lib/skills.ts

​
Publishing Workflow

The publish script (scripts/skills/publish-skill.ts) handles the full flow:
  1. Reads SKILL.md, parses frontmatter (requires name + description)
  2. POSTs { name, description, skill_md, content_type, category, tags, version } to /v1/skills
  3. Flips is_public: true via PUT /skills/:id so the skill is network-discoverable
  4. Outputs the skill_id — add it to SKILL_IDS in lib/skills.ts to wire a stable handle
Use --dry-run to preview without publishing, or --private to keep a skill staged privately.

​
Architecture

  • lib/skills.ts — registry mapping friendly names to StackNet skill UUIDs (SKILL_IDS) and label helpers for @-mention pills
  • lib/skills-client.ts — creates SkillsClient instances (client + server) via @stacknet/stacks, pointing at the StackNet base URL
  • lib/stacknet-skills.ts — server-side fetch + cache layer. Caches SkillRecord (including full skill_md) for 5 minutes. Usage tracking via bumpSkillUsage() is fire-and-forget — never blocks the user-visible stream
  • Studio UI (/studio/skills) — shopping-cart “Flow” pattern browsing rack repos with kind: skill, filterable by category tags
  • HQ UI (/hq/skills) — three-pane SkillsLibrary from @stacknet/agentutils, driven by the workspace’s default catalog
  • MCP server — exposes skills_list, skills_get, skills_invoke, skills_publish wrapping the catalog API

Geoff Code Skills

Local skill discovery, directory layout, and activation in the CLI.

MCP Tools Reference

Skills tools: list, get, invoke, publish.