Skill

Skill Definition Template (Agent Skills Spec)

Creates well-structured, spec-compliant skill definitions following the Agent Skills open standard. Skills work with any compatible AI tool - Claude, Gemini CLI, Cursor, VS Code, OpenAI Codex, and more.

When to Use

• Defining a new skill
• Updating an existing skill's content
• Improving skill triggering and descriptions
• Following the agentskills.io specification

Skill Structure

---
name: {skill-name}
description: {Does X for Y context}. Use when {trigger 1}, {trigger 2}, or {trigger 3}.
metadata:
  author: {team}
  version: "1.0"
---

# {Skill Title}

{One-line summary of what this skill provides.}

## {Core Content}

{Primary patterns, conventions, or rules.}

## {Examples}

{Code examples, templates, or reference material.}

## {Checklist}

{Actionable checklist for using this skill.}

Frontmatter Reference

Required Fields

Optional Fields

Description Best Practices

The description is the most important field - it determines when agents activate the skill.

Formula: [What it does] + [When to use it]

# Good - specific with triggers
description: NestJS + Clean Architecture patterns for backend. Use when creating services, modules, or implementing features.

# Bad - too vague
description: Helps with projects.

# Bad - missing triggers
description: Creates documentation systems.

Progressive Disclosure

• Put the 80% use case in the body
• Put the remaining 20% in reference documents (knowstack.save_documents)
• Target body under 500 lines

Skill Types

Content Guidelines

• Lead with the most critical information
• Use tables for structured data
• Use code blocks for patterns (not prose)
• Prefer checklists over paragraphs for actionable items
• Be prescriptive about conventions, flexible about implementation details

Anti-Patterns

Creation Checklist

Frontmatter

• name is 1-64 chars, kebab-case, no consecutive hyphens
• description follows Does X. Use when Y. pattern
• description under 500 characters
• metadata.version quoted as string

Body

• Starts with # Title and one-line summary
• Core patterns in the first section
• Code examples for non-obvious patterns
• Actionable checklist where applicable
• Under 500 lines total

Quality

• No duplicate content with other skills
• No IDE-specific paths
• Progressive disclosure respected
• Tested by invoking and verifying behavior

Managing Skills via MCP

Create or Update

knowstack.save_skills(name: "{skill-name}", description: "{Does X. Use when Y.}", content: "{full content}")

List All

knowstack.get_skills()

Get Full Content

knowstack.get_skills(name: "{skill-name}")

Search

knowstack.search_instructions(q: "{keyword}", type: "SKILL")

Check Existing

Always use knowstack.get_skills() to list available skills before creating new ones to avoid duplication.

Save

After creating a skill definition, save it:

knowstack.save_skills(name: "{skill-name}", description: "{description}", content: "{full content}")