Creating Custom Skills

Custom skills let you give Yukkai expertise in any domain — from a specific framework to your company's internal coding standards. This guide walks through the process.

The create Action

skill(action: "create",
  name: "Kubernetes",
  description: "Kubernetes deployment and management expertise",
  system_prompt: "You are a Kubernetes expert. Follow these principles: ...",
  activation_keywords: ["k8s", "kubernetes", "helm", "kubectl", "manifest"],
  file_patterns: "*.yaml,*.yml,k8s/**",
  tags: "devops, infrastructure, k8s",
  preferred_tools: "bash, file_read, file_write, grep"
)

Parameters

Parameter	Required	Description
name	✅	Skill name (must be unique)
description	✅	Short description shown in the skill list
system_prompt	✅	The full system prompt defining the skill's expertise
activation_keywords	❌	Comma-separated keywords that trigger auto-activation
file_patterns	❌	File glob patterns for project-based auto-detection
tags	❌	Comma-separated tags for organization
preferred_tools	❌	Comma-separated list of tools this skill prefers

Writing a Good System Prompt

The system prompt is the heart of the skill. Here's what makes a good one:

Be Specific and Narrow

❌ Bad (too broad):

You are a great programmer who writes good code.

✅ Good (specific):

You are a Kubernetes expert specializing in production deployments.
Follow these principles:
- Always define resource limits and requests
- Use namespaces for environment isolation
- Prefer Deployments over ReplicaSets
- Include liveness and readiness probes
- Use ConfigMaps for non-sensitive configuration
- Use Secrets for sensitive data, never base64 in manifests

Include Conventions

If your team has specific conventions, encode them:

- All Helm charts must use semantic versioning (MAJOR.MINOR.PATCH)
- Namespace naming: <team>-<environment> (e.g., payments-prod)
- Every deployment must have a matching HPA

Include Domain Knowledge

Reference key concepts, patterns, and gotchas:

Common pitfalls to avoid:
- Do not use :latest tag in production
- Do not mount secrets as environment variables in shared namespaces
- Always set imagePullPolicy: IfNotPresent in production

File Patterns for Auto-Detection

File patterns enable project-based skill activation. When you open or reference a project whose files match the patterns, the skill activates automatically:

file_patterns: "*.yaml,*.yml,k8s/**,helm/**"

This uses standard glob syntax:

• *.swift — all Swift files
• **/*.swift — all Swift files recursively
• k8s/** — everything under a k8s/ directory

Learning Skills from a Project

Instead of writing a skill from scratch, you can have Yukkai analyze an existing project and auto-generate a skill:

skill(action: "learn", path: "/Users/you/Projects/MyK8sProject")

Yukkai will:

1. Analyze the project's file structure and patterns
2. Identify conventions, frameworks, and dependencies
3. Generate a skill with appropriate activation keywords and file patterns
4. Create a system prompt based on observed patterns

You can then review and refine the generated skill using update.

Updating a Skill

skill(action: "update", id: "kubernetes",
  system_prompt: "Updated instructions...",
  activation_keywords: "k8s,kubernetes,helm,kubectl,manifest,argocd"
)

You can update any field. This is useful for iterating on a skill's system prompt as you refine the domain knowledge.

Deleting a Skill

skill(action: "delete", id: "kubernetes")

Only custom skills (author: user) can be deleted. Built-in skills can only be deactivated.

Best Practices

1. Check for overlap first — Run skill(action: "list") and skill(action: "search", query: "...") to avoid duplicating an existing skill's domain.
2. Keep scope narrow — One clear domain per skill. Don't create a "general programming" skill.
3. Iterate — Start with a basic system prompt, use it, then refine with update based on results.
4. Use learn when possible — Analyzing an existing project often produces better activation keywords and file patterns than guessing.
5. Include preferred tools — This hints to the system which tools are most relevant, optimizing the experience.