synapsync/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:

1. User message context — If the user's message contains file paths, extract {output_dir} from those paths
2. Auto-discover — Scan for .agents/skill-creator/ in {cwd}
3. Ask the user — If nothing found, ask where to save the skill scaffold. Default suggestion: .agents/skill-creator/{scope}/ (where {scope} is the topic, e.g., new-react-skill, api-validator)

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

---

Categories

| Category | Purpose | | -------------- | ------------------------------------------- | | general | General-purpose skills, internal AI tooling | | frontend | UI, React, CSS, components | | backend | APIs, servers, backend services | | database | Database queries, migrations, ORMs | | devops | CI/CD, infrastructure, deployment | | security | Security analysis, vulnerability scanning | | testing | Testing strategies, QA automation | | analytics | Data analysis, research, benchmarking | | automation | Task automation, workflows | | integrations | External services (Supabase, Stripe, etc.) |

---

SKILL.md Templates

Available Templates:

• Basic Template: assets/SKILL-TEMPLATE-BASIC.md - For simple, single-purpose skills
• Advanced Template: assets/SKILL-TEMPLATE-ADVANCED.md - For complex skills with workflows

When creating a new skill, use the appropriate template as your starting point.

Basic Template (Simple Skills)

Use for: Single-purpose skills without workflows, integrations, or complex configurations

File: assets/SKILL-TEMPLATE-BASIC.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
---

## 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

```{language}
{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](assets/SKILL-TEMPLATE-ADVANCED.md)

```markdown
---
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 (<70%): {description}

Output Structure (if skill produces artifacts)

Report/File Sections

1. Section 1: What it contains
2. Section 2: What it contains
3. 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

1. {Preparation step 1}
2. {Preparation step 2}

During Execution

1. {Execution guideline 1}
2. {Execution guideline 2}

After Completion

1. {Post-execution step 1}
2. {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

1. {Limitation Category}: {Description of what cannot be done}
2. {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)

1. Purpose: One clear sentence explaining the skill's goal
2. When to Use This Skill: 3-5 concrete use cases
3. Critical Patterns: The most important rules AI must know
4. Code Examples: At least 1-2 focused examples
5. 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 (<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 & 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