skill-creator

When to Create a Skill

Skill Evaluation Checklist

Before creating a skill, ALL of these must be YES:

Reusable? - Pattern will be used 3+ times
Stable? - Pattern won't change frequently
Valuable? - Provides guidance beyond obvious best practices
Explicit trigger? - Clear action/context that invokes it
No existing equivalent? - Similar skill doesn't already exist

If ANY answer is NO → Do NOT create the skill.

Create a skill when:

A pattern is used repeatedly and AI needs guidance
Project-specific conventions differ from generic best practices
Complex workflows need step-by-step instructions
Decision trees help AI choose the right approach

Don't create a skill when:

Documentation already exists (create a reference instead)
Pattern is trivial or self-explanatory
It's a one-off task
When in doubt: DEFAULT TO NO - It's easier to add a skill later than to maintain unnecessary ones

Common Anti-Patterns

Avoid these mistakes when creating skills:

Anti-Pattern 1: Duplicating Existing Documentation

Problem: Creating a skill that just repeats what's already in project docs Instead: Create a skill with a references/ folder pointing to existing docs, or add context that docs don't provide

Anti-Pattern 2: Vague or Missing Triggers

Problem: Trigger: When using React (too broad) Instead: Trigger: When writing React 18 components/hooks in .tsx (Vite, React Router) (specific)

Anti-Pattern 3: Overloaded Skills

Problem: Single skill trying to cover testing, deployment, AND monitoring Instead: Create separate focused skills: myapp-test , myapp-deploy , myapp-monitor

Anti-Pattern 4: Missing auto_invoke

Problem: Skills that should be auto-invoked but lack the metadata Instead: Always add metadata.auto_invoke with clear action description

Anti-Pattern 5: Generic Names

Problem: utils , helpers , common (meaningless) Instead: typescript-types , api-client , error-handling (descriptive)

Anti-Pattern 6: Toy Examples

Problem: Code examples with foo , bar , example1

Instead: Real-world patterns with actual domain names and realistic use cases

Anti-Pattern 7: No "Why" Explanations

Problem: Just showing code without explaining reasoning Instead: Add "Why:" after critical patterns to explain the rationale

Anti-Pattern 8: Forgetting allowed-tools

Problem: Skills that need specific tools but don't declare them Instead: Always specify allowed-tools in frontmatter

Anti-Pattern 9: Web URLs in References

Problem: Linking to external websites that may change Instead: Use local paths (docs/developer-guide/*.mdx ) or copy essential info

Anti-Pattern 10: Skipping Sync Command

Problem: Creating skill but forgetting to synchronize the project Instead: Always run synapsync sync after creating a new skill to update symlinks for all providers

Configuration Resolution

{output_dir} is the directory where skill-creator stores generated skill scaffolds. Resolve it once at the start:

User message context — If the user's message contains file paths, extract {output_dir} from those paths
Auto-discover — Scan for .agents/skill-creator/ in {cwd}
Ask the user — If nothing found, ask where to save the skill scaffold. Default suggestion: .agents/skill-creator/{project-name}/

No AGENTS.md. No branded blocks. The output directory is resolved at runtime.

Skill Structure

{output_dir}/skills/{category}/{skill-name}/ ├── SKILL.md # Required - main skill file ├── assets/ # Optional - templates, schemas, examples │ ├── template.py │ └── schema.json └── references/ # Optional - links to local docs └── docs.md # Points to project docs

name: { skill-name } description: > {One-line description of what this skill does}. Trigger: {When the AI should load this skill}. license: Apache-2.0 metadata: author: synapsync version: "1.0" scope: [root] auto_invoke: "{Action that triggers this skill}" allowed-tools: Read, Edit, Write, Glob, Grep, Bash

Purpose

{One clear sentence explaining the skill's goal}

When to Use This Skill

{Concrete use case 1}
{Concrete use case 2}
{Concrete use case 3}

Critical Patterns

{The most important rules - what AI MUST know}

Code Examples

{Minimal, focused examples with comments}

Commands

{Common commands with descriptions}

Resources

Templates: See assets/ for {description}
Documentation: See references/ for local docs

Advanced Template (Complex Skills)

Use for: Skills with workflows, reports, integrations, or safety concerns

File: assets/SKILL-TEMPLATE-ADVANCED.md

---
name: {skill-name}
description: >
  {One-line description of what this skill does}.
  Trigger: {When the AI should load this skill}.
license: Apache-2.0
metadata:
  author: synapsync
  version: "1.0"
  scope: [root]
  auto_invoke: "{Action that triggers this skill}"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
---

## Purpose
{One clear sentence explaining the skill's goal}

## When to Use This Skill
- {Concrete use case 1}
- {Concrete use case 2}
- {Concrete use case 3}

## Capabilities
{Detailed breakdown of what this skill can do}

### Category 1
- Capability A
- Capability B

### Category 2
- Capability C
- Capability D

## Supported Languages/Frameworks (if applicable)
### Primary Support
- **Technology 1**: Specific versions or variants
- **Technology 2**: Specific versions or variants

### Analysis/Implementation Techniques
- Technique 1
- Technique 2

## Workflow (for multi-step processes)

### Step 1: {Phase Name}
{Description of what happens in this phase}

### Step 2: {Phase Name}
{Description of what happens in this phase}

### Step 3: {Phase Name}
{Description of what happens in this phase}

## Command Examples

### Basic Usage
```bash
{Simple command example}

Targeted Usage

{More specific command example}

Advanced Options

{Complex command with options}

Configuration Options (if applicable)

{Option Category 1}

- Option A: Description

- Option B: Description

{Option Category 2}

- High (>90%): {description}

- Medium (70-90%): {description}

- Low (&#x3C;70%): {description}

Output Structure (if skill produces artifacts)

Report/File Sections

- Section 1: What it contains

- Section 2: What it contains

- Section 3: What it contains

Critical Patterns

{The most important rules - what AI MUST know}

Code Examples

{Minimal, focused examples with comments}

Best Practices

Before Running

- {Preparation step 1}

- {Preparation step 2}

During Execution

- {Execution guideline 1}

- {Execution guideline 2}

After Completion

- {Post-execution step 1}

- {Post-execution step 2}

Integration with Other Skills (if applicable)

With {skill-name}

- {Integration point or use case}

With {skill-name}

- {Integration point or use case}

Limitations

- {Limitation Category}: {Description of what cannot be done}

- {Limitation Category}: {Description of what cannot be done}

Safety Features (for destructive operations)

- {Safety Feature 1}: {Description}

- {Safety Feature 2}: {Description}

- {Safety Feature 3}: {Description}

Troubleshooting

Issue: "{Common Problem}"

Solution: {How to fix it}

Issue: "{Common Problem}"

Solution: {How to fix it}

Example Output (if applicable)

{Realistic example of what the skill produces}

Naming Conventions

Type
Pattern
Examples

Generic skill
{technology}

pytest
, playwright
, typescript

Project-specific
{project}-{component}

myapp-api
, myapp-ui
, myapp-checks

Testing skill
{project}-test-{component}

myapp-test-api
, myapp-test-ui

Workflow skill
{action}-{target}

skill-creator
, jira-task

Decision: assets/ vs references/

Need code templates? → assets/
Need JSON schemas? → assets/
Need example configs? → assets/
Link to existing docs? → references/
Link to external guides? → references/ (with local path)

Key Rule: references/
 should point to LOCAL files (docs/developer-guide/*.mdx
), not web URLs.

Decision: Project-Specific vs Generic

Patterns apply to ANY project? → Generic skill (e.g., pytest, typescript)
Patterns are project-specific? → {project}-{name} skill
Generic skill needs project info? → Add references/ pointing to project docs

Frontmatter Fields

Field
Required
Description

name

Yes
Skill identifier (lowercase, hyphens)

description

Yes
What + Trigger in one block

license

Yes
License identifier (e.g., Apache-2.0
, MIT
)

metadata.author

Yes
Author or organization name

metadata.version

Yes
Semantic version as string

Template Selection Guide

Simple, single-purpose skill? → Use Basic Template
Complex workflow with multiple steps? → Use Advanced Template
Skill produces reports/files? → Use Advanced Template
Skill has safety concerns? → Use Advanced Template
Skill integrates with other skills? → Use Advanced Template

Template Guidelines

When generating a new skill, include sections based on complexity:

Core Sections (Always Include)

- Purpose: One clear sentence explaining the skill's goal

- When to Use This Skill: 3-5 concrete use cases

- Critical Patterns: The most important rules AI must know

- Code Examples: At least 1-2 focused examples

- Commands: Copy-paste ready commands with descriptions

Optional Sections (Include if Relevant)

- Capabilities: For skills with multiple features (break into categories)

- Workflow: For multi-step processes (numbered steps)

- Command Examples: Multiple complexity levels (Basic/Targeted/Advanced)

- Configuration Options: For configurable skills (group by category)

- Supported Languages/Frameworks: For language-specific skills

- Output Structure: For skills that generate reports/files

- Best Practices: Pre/during/post execution guidance (phased approach)

- Integration with Other Skills: How this skill works with existing skills

- Limitations: Be transparent about what the skill cannot do

- Safety Features: For destructive operations (explicit safeguards)

- Troubleshooting: Common issues and solutions (FAQ format)

- Example Output: Show realistic output (with proper formatting)

- Obsidian Output Standard: If the skill writes .md
 files to {output_dir}
, it MUST include a ## Obsidian Output Standard
 section with the appropriate Obsidian output rules inline (frontmatter schema, wiki-links, type taxonomy, bidirectional references)

Style Guidelines

Visual Hierarchy

- Use emojis sparingly for visual scanning

- Use bold for emphasis on key terms

- Use tables for comparisons and decision trees

- Use code fences with language identifiers

Writing Style

- Start sections with action verbs

- Use present tense for descriptions

- Be concise but complete

- Include "why" not just "what"

Code Examples

- Include language identifier in code fences

- Add inline comments to explain non-obvious parts

- Show both correct and incorrect patterns when helpful

- Keep examples realistic and production-like

Confidence Levels (for recommendations)

- High (>90%): Safe to execute

- Medium (70-90%): Review recommended

- Low (&#x3C;70%): Manual investigation required

Command Format

# Description of what this command does
command --flag argument

Content Guidelines

DO

- Start with the most critical patterns (priority-first)

- Use tables for decision trees and comparisons

- Keep code examples minimal and focused

- Include Commands section with copy-paste commands

- Show realistic examples (not toy examples)

- Include confidence levels for recommendations

- Use phased approaches (Before/During/After)

- Be transparent about limitations

- Show integration points with other skills

- Include troubleshooting for common issues

DON'T

- Add Keywords section (agent searches frontmatter, not body)

- Duplicate content from existing docs (reference instead)

- Include lengthy explanations (link to docs)

- Use generic/toy examples (show real-world patterns)

- Use web URLs in references (use local paths)

- Make skills too broad (keep focused)

- Skip the "Purpose" section (always required)

- Forget to include "allowed-tools" in frontmatter

Syncing the Project After Skill Creation

After creating a new skill, you should synchronize the project to make it available to AI assistants across all enabled providers.

How to Sync

Run the CLI sync command:

synapsync sync

What This Does

The sync command performs a double synchronization:

1. Manifest Sync

- Scans {output_dir}/
 filesystem for all cognitives

- Compares with manifest.json
 (the registry of installed cognitives)

- Adds new cognitives (created locally by AI) with source: "local"

- Removes entries for deleted cognitives

- Updates manifest.json

2. Provider Sync

- For each enabled provider (claude, cursor, etc.):

- Creates symlinks from provider directory to central storage

- Example: .claude/skills/react-hooks
 → ../../{output_dir}/skills/frontend/react-hooks

- Removes orphaned symlinks (cognitive no longer exists)

Directory Structure After Sync

project/
├── {output_dir}/                          # Central storage (source of truth)
│   ├── manifest.json                    # Registry of all cognitives
│   └── skills/
│       └── frontend/
│           └── react-hooks/
│               └── SKILL.md             # The actual skill file
│
├── .claude/                             # Claude provider (symlinks)
│   └── skills/
│       └── react-hooks -> ../../{output_dir}/skills/frontend/react-hooks
│
└── .cursor/                             # Cursor provider (symlinks)
    └── skills/
        └── react-hooks -> ../../{output_dir}/skills/frontend/react-hooks

No Manual Copying Required

You do NOT need to manually copy skills to each provider folder. The CLI creates symlinks from each provider's skills directory back to the central {output_dir}/skills/
 folder.

IMPORTANT: Always run synapsync sync
 after creating, modifying, or deleting skills to keep your project synchronized with all providers.

Real-World Examples

Example 1: Simple Skill (Basic Template)

Skill: typescript-types

Structure:

- Purpose

- When to Use This Skill

- Critical Patterns

- Code Examples

- Commands

Why Basic Template: Single-purpose, no workflow, no integrations needed.

Example 2: Complex Skill (Advanced Template)

Skill: dead-code-hunter

Structure:

- Purpose

- When to Use This Skill

- Capabilities (with categories)

- Supported Languages &#x26; Frameworks

- Workflow (4 steps)

- Command Examples (Basic/Targeted/Advanced)

- Configuration Options

- Output Structure

- Best Practices (Before/During/After)

- Integration with Other Skills

- Limitations

- Safety Features

- Troubleshooting

- Example Output

Why Advanced Template: Multi-step workflow, produces reports, has safety concerns, integrates with other skills.

Decision Trees

Should This Be a Skill?

Is pattern used repeatedly?
├─ No → Don't create skill
└─ Yes
   └─ Is it project-specific or generic?
      ├─ Generic → Create generic skill (e.g., `pytest`)
      └─ Project-specific
         └─ Does existing documentation cover it?
            ├─ Yes → Create reference instead
            └─ No → Create {project}-{component} skill

Which Template Should I Use?

Does skill have multiple steps?
├─ Yes → Advanced Template
└─ No
   └─ Does skill produce files/reports?
      ├─ Yes → Advanced Template
      └─ No
         └─ Does skill have safety concerns?
            ├─ Yes → Advanced Template
            └─ No → Basic Template

Which Sections Should I Include?

Core sections (always):
- Purpose
- When to Use This Skill
- Critical Patterns
- Code Examples
- Commands

Optional sections (add if relevant):
- Capabilities → If skill has multiple features
- Workflow → If skill has multi-step process
- Command Examples (multiple levels) → If skill has varying complexity
- Configuration Options → If skill is configurable
- Supported Languages → If skill is language-specific
- Output Structure → If skill produces artifacts
- Best Practices → If skill has phases (Before/During/After)
- Integration with Other Skills → If skill composes with others
- Limitations → If skill has known constraints
- Safety Features → If skill can cause data loss/changes
- Troubleshooting → If skill has common issues
- Example Output → If output format matters

Checklist Before Creating

-  Skill doesn't already exist (check {output_dir}/skills/
)

-  Pattern is reusable (not one-off)

-  Name follows conventions (lowercase, hyphens)

-  Category is correct (general/frontend/backend/devops/security/testing/etc.)

-  Template selected (Basic vs Advanced)

-  Frontmatter is complete:

-  name
 field

-  description
 with trigger keywords

-  license
 field

-  metadata.author
 field

-  metadata.version
 field

-  metadata.scope
 field (usually [root]
)

-  metadata.auto_invoke
 field (if applicable)

-  allowed-tools
 field

-  Core sections included:

-  Purpose

-  When to Use This Skill

-  Critical Patterns

-  Code Examples

-  Commands

-  Optional sections (if applicable):

-  Capabilities

-  Workflow

-  Configuration Options

-  Best Practices

-  Limitations

-  Troubleshooting

-  Code examples are realistic (not toy examples)

-  Commands are copy-paste ready

-  No web URLs in references (local paths only)

-  Run synapsync sync
 after creation

Resources

Templates

- Basic Template: assets/SKILL-TEMPLATE-BASIC.md - For simple skills

- Advanced Template: assets/SKILL-TEMPLATE-ADVANCED.md - For complex skills

References

- Examples: Review existing skills in {output_dir}/skills/
 for reference patterns

- SynapSync Registry: https://github.com/SynapSync/skills-registry - Public skill repository

Safety Notice

Copy this and send it to your AI assistant to learn

Purpose

When to Use This Skill

Critical Patterns

Code Examples

Advanced Template (Complex Skills)

Source Transparency

Related Skills

obsidian

universal-planner

sprint-forge