Add skill creation guidelines based on superpowers writing-skills

[devrimcavusoglu]

Summary

Integrate skill creation guidelines into skern's skern skill create workflow, inspired by the superpowers writing-skills skill. These guidelines should be built into skern itself so that agents (and humans) produce high-quality, discoverable, well-structured skills by default.

Motivation

Currently, skern provides the tooling for managing skills (create, install, list, search, etc.) but lacks opinionated guidance on how to write effective skills. The superpowers project has developed comprehensive skill authoring guidelines that cover:

• When to create a skill (and when not to)
• Skill types (technique, pattern, reference)
• SKILL.md structure — recommended sections (Overview, When to Use, Core Pattern, Quick Reference, Common Mistakes)
• Claude Search Optimization (CSO) — writing descriptions and keywords so agents can discover skills effectively
• Description best practices — start with "Use when...", focus on triggering conditions, never summarize workflow (agents may shortcut and skip reading the full skill)
• Token efficiency — keeping frequently-loaded skills concise, using cross-references, compressing examples
• Naming conventions — verb-first, active voice, gerunds for processes
• File organization — when to keep everything inline vs. split into supporting files
• Code examples — one excellent example beats many mediocre ones
• Flowchart usage — only for non-obvious decision points, never for linear instructions or reference material
• Anti-patterns — narrative storytelling, multi-language dilution, generic labels, code in flowcharts
• Skill creation checklist — structured checklist for quality assurance

Proposed Scope

1. Enhance skern skill create scaffolding — embed the writing-skills guidelines into the skill creation flow itself (e.g., scaffold templates, inline comments in generated SKILL.md, validation hints). This should be the default behavior, not an opt-in flag. When an agent or human runs skern skill create, the output should naturally guide them toward well-structured skills.
2. Update AGENTS.md — add the writing-skills guidelines as the canonical reference for how skern creates skills. Agents operating on skern should follow these guidelines when creating or editing skills.
3. Optionally add a docs/guides/writing-skills.md page to the documentation site for human reference.

Key Principles to Incorporate

• Description field: Should start with "Use when..." and describe triggering conditions only — never summarize the skill's workflow (agents may follow the description shortcut instead of reading the full SKILL.md)
• Naming: Use kebab-case, verb-first active voice (e.g., creating-skills not skill-creation)
• Token budget: Getting-started skills < 150 words; frequently-loaded < 200 words; others < 500 words
• Structure: Overview → When to Use → Core Pattern → Quick Reference → Common Mistakes
• One excellent example per skill, in the most relevant language
• Flat namespace: All skills in one searchable directory
• Supporting files only for heavy reference (100+ lines) or reusable tools

Reference

• Source: https://github.com/obra/superpowers/tree/main/skills/writing-skills

[devrimcavusoglu]

Compliance Analysis: writing-skills vs Skern Format

Analyzed the superpowers writing-skills SKILL.md against skern's validation rules and format. Here are the non-compliant parts that need adaptation:

1. Frontmatter Spec Mismatch

The skill states "Only two fields supported: name and description". Skern supports name, description, tags, allowed-tools, and metadata (with author, version, modified-by). The documentation section must be updated to reflect skern's full spec.

2. Missing metadata in Frontmatter

The skill's own frontmatter only has name and description — no metadata block. Skern warns on missing metadata.author.name and defaults version to 0.0.1. Needs a full metadata block added.

3. Name Casing Convention Conflict

Example name Skill-Name-With-Hyphens uses title-case. Skern requires ^[a-z0-9]+(-[a-z0-9]+)*$ (lowercase only). All name examples must be lowercased.

4. External File References (superpowers-specific)

Body references files that only exist in the superpowers repo:

• @graphviz-conventions.dot, @testing-skills-with-subagents.md (superpowers cross-references)
• anthropic-best-practices.md, persuasion-principles.md, render-graphs.js

These will trigger ValidateFolder warnings. The @ loading mechanism is superpowers-specific and irrelevant to skern.

5. Superpowers-Specific Tooling

References to TodoWrite, render-graphs.js, search-conversations, and superpowers-specific workflows need to be replaced with skern equivalents or removed.

6. Graphviz Flowcharts

Contains Graphviz dot syntax blocks. Skern skills don't have graphviz rendering — convert to plain markdown decision trees or remove.

7. HTML-like Tags (<Bad>, <Good>)

Uses custom HTML tags for examples. Harmless in markdown but non-standard — can be kept or replaced with blockquotes/headers.

8. TDD/Testing Methodology Scope

Heavy dependency on superpowers' testing-skills-with-subagents workflow and persuasion psychology references. Keep the high-level TDD principle but trim the detailed subagent pressure-testing methodology.