skill-creator

name	skill-creator
description	How to create new skills for this HQ — format, frontmatter, content structure. Use when you need to add a new skill to this repository, or when reviewing whether an existing skill is well-formed.

Skill Creator

What is a Skill?

A skill is a reference document that gives an AI agent (or a developer) deep, actionable knowledge for a specific domain. It is not a README, a tutorial, or a one-liner tip. It contains real patterns, real code, and clear guidance on what NOT to do.

File Location

skills/
└── <skill-name>/
    └── SKILL.md

Skill names are lowercase, hyphenated: api-design-patterns, auth-patterns, docker-patterns.

Required Structure

---
name: skill-name
description: One-line description. Use when [specific trigger condition].
---

# Title

## [Section 1]
[Content with real code examples]

## [Section 2]
...

## Forbidden Patterns
[What NOT to do — these are as important as the positive guidance]

Frontmatter Rules

---
name: skill-name          # must match the directory name
description: >            # one line: what it does + when to trigger
  Generates Excel files with ExcelJS. Use when creating .xlsx exports
  from database data in a NestJS app.
---

The description field is what an AI uses to decide whether to load this skill. Make the trigger condition specific:

# Good — specific trigger
description: JWT access/refresh tokens, Passport.js strategies. Use when implementing auth in a NestJS + Next.js app.

# Bad — too vague
description: Authentication patterns. Use when building auth.

Content Rules

1. Real code, not pseudocode

Every code block must be runnable with the imports shown. Never use ... to hide required setup.

// Good — complete, runnable snippet
import { Injectable } from '@nestjs/common'
import { InjectRepository } from '@nestjs/typeorm'
import { Repository } from 'typeorm'
import { User } from './user.entity'

@Injectable()
export class UsersRepository {
  constructor(
    @InjectRepository(User)
    private readonly repo: Repository<User>
  ) {}

  findById(id: number) {
    return this.repo.findOne({ where: { id } })
  }
}

// Bad — too abstract
class MyRepo {
  // inject the repo here
  findById(id) { ... }
}

2. Forbidden Patterns section is mandatory

The "Forbidden Patterns" section must be the last section. List 5-10 concrete things that cause real bugs, security issues, or maintenance problems.

## Forbidden Patterns

- Never store access tokens in localStorage — XSS can steal them
- Never use the same JWT secret for access and refresh tokens
- Never skip `@IsEmail()` validation on email fields

3. Aim for 200-400 lines

• Under 200 lines: too shallow, not useful as a reference
• Over 400 lines: likely covering too many topics, should be split

4. One topic per skill

Don't mix unrelated concerns. If you're writing a testing skill, don't include deployment. If the topic is naturally broad, split it:

# Too broad:
skills/backend/SKILL.md  ← covers NestJS + TypeORM + auth + caching

# Better:
skills/backend-dev-guidelines/SKILL.md   ← NestJS layering
skills/auth-patterns/SKILL.md            ← JWT + Passport
skills/docker-patterns/SKILL.md          ← Containerization

Section Patterns to Follow

Command blocks for setup

npm install exceljs
npm install -D @types/node

Configuration files

Show actual config files, not fragments.

Patterns with comparison (good vs bad)

// Bad: explanation of why it's bad
const bad = doWrongThing()

// Good: explanation of why it's better
const good = doRightThing()

Checklists for pre-flight checks

Production Deployment Checklist:
□ NODE_ENV=production set
□ Secrets validated at startup
□ Health checks responding
□ Rate limiting enabled

Quality Checklist

Before merging a new skill:

□ Frontmatter has name + description
□ name matches directory name
□ Description includes "Use when [specific condition]"
□ Code examples are complete (have imports, no ellipsis hiding setup)
□ At least 3 major sections with real content
□ "Forbidden Patterns" section exists and has 5+ entries
□ 200-400 lines total
□ No tutorial prose — reference-style only
□ TypeScript/language specifics match the project stack

Example: Creating a New Skill

# 1. Create the directory and file
mkdir skills/redis-patterns
touch skills/redis-patterns/SKILL.md

# 2. Write the skill following the template above

# 3. Commit
git add skills/redis-patterns/SKILL.md
git commit -m "feat: add redis-patterns skill"

Forbidden Patterns

• Never write a skill that's just a list of links — content must be here, not linked
• Never use placeholders like [your code here] — write the actual code
• Never mix two unrelated domains in one skill — split instead
• Never skip the "Forbidden Patterns" section — negative examples are the most valuable
• Never write in tutorial style ("first you need to...") — use reference style (show the code)
• Never omit the trigger condition from the description — it's what activates the skill