ai-mindset-org/pos-skill-factory

POS Skill Factory — Build Skills from Ideas

Create a production-quality Claude Code skill from a natural language description. Uses 4 template patterns from real POS implementations, validates against a quality checklist, and installs to the right location.

Step 1: Understand the Idea

Parse {idea} and determine:

1. Core action — scan, generate, send, transform, aggregate, analyze, summarize
2. Inputs — files, MCP data, user input, context, CLI args
3. Outputs — terminal text, file, message, HTML, structured data
4. Tools needed — Read/Write, Bash, Grep, Glob, MCP, ToolSearch, Task (sub-agents)
5. Pattern — which of the 4 templates fits best

Step 2: Select Template Pattern

Pattern A: Audit (scan + score + suggest)

When: skill examines a system, counts things, produces a score. Structure: discover sources → scan each → aggregate → score → suggest gaps. Real examples: /pos-audit (POS infrastructure), vault-cleanup (Obsidian maintenance), security-scan (secrets/permissions).

## Step 0: Discover sources
  {read mcp.json, find files, check configs}
## Step 1-N: Scan each source
  {extract data, categorize, count}
## Output: scored report
  {box-drawing table with score breakdown}
## Scoring table
  {component | points | criteria}
## Gap suggestions
  {score range → recommended action}

Pattern B: Pipeline (gather + synthesize + output)

When: skill pulls from multiple sources and synthesizes a result. Structure: detect integrations → gather from each (with degradation) → synthesize → output in chosen format. Real examples: /pos-morning (daily brief), /daily-focus (5 parallel agents → brief + visual card), /research (multi-angle Exa search → synthesis).

## Step 0: Detect integrations
  {read mcp.json, build source map}
## Step 1: Gather from each source
  {degradation chain: MCP → bash fallback → skip}
## Step 2: Synthesize
  {derive insight from combined data}
## Step 3: Output
  {multiple format options: terminal, file, message}

Key Pipeline pattern: always start with MCP detection and use graceful degradation chains:

Calendar: Krisp MCP → gcal script → skip
Tasks: Linear MCP → cache file → local TODO → skip
Messages: Telegram MCP → skip

Pattern C: Generator (input + transform + write)

When: skill takes input and produces a file or artifact. Structure: parse input → apply template/rules → write output → verify. Real examples: /pos-dashboard-gen (HTML dashboard), /deck (HTML presentations), /imagine (image generation via API).

## Step 1: Parse input
  {args or interactive questions}
## Step 2: Build artifact
  {HTML, markdown, image, etc.}
## Step 3: Write and verify
  {write file, check size, open in browser/app}
## Design system (if visual)
  {CSS variables, fonts, color scheme}

Pattern D: Integrator (detect + connect + execute)

When: skill wraps an external service with opinionated defaults. Structure: ToolSearch → build payload → show preview → confirm → execute → report. Real examples: /linear-action (Linear CRUD with pre-fill), /telegram (MTProto messaging), /calendar (gcal with fallback chain).

## Step 0: Load MCP tools
  {ToolSearch: "+server_name"}
## Step 1: Build payload
  {pre-fill from context — session topic, recent work}
## Step 2: Preview → confirm
  {show what will happen, ask y/edit/skip}
## Step 3: Execute and report
  {MCP call, format result}

Key Integrator pattern: always pre-fill then confirm:

AIM-2054 · Sprint review prep · ◐ IP
action: update
comment: "completed slide deck, ready for review"
→ execute? [y/edit/skip]

Step 3: Generate Skill Name

Rules:

• Lowercase, hyphenated: morning-brief, weekly-review, task-sorter
• 2-3 words max: never more than 3
• Verb-noun preferred: check-tasks, send-digest, scan-vault
• No generic verbs: avoid do-, run-, make- — be specific
• No project prefix: user adds their own prefix (e.g., aim-)

Validation: name must complete "I want to _____" naturally.

• Good: "I want to check-tasks"
• Bad: "I want to task-thing"

Step 4: Generate SKILL.md

Follow Claude Code skill spec exactly:

---
name: {skill-name}
description: {ONE line — what it does. Must fit in a skill listing.}
version: 1.0
user_invocable: true
arguments:          # only if skill takes parameters
  - name: {param}
    description: "{what it controls}"
    required: false
---

# {Title} — {Subtitle}

{2-3 sentences: what, why, when.}

## Step 0: {Detect/Discover} (if MCP-dependent)

{Read ~/.claude/mcp.json, ToolSearch for servers}

## Step N: {Action}

{Specific instructions with:
- Exact tool calls (Read, Write, Bash, Grep, Glob, ToolSearch)
- MCP function names
- Degradation chains (try A → try B → skip)
- What to do with the data}

## Output Format

{EXACT format with box-drawing characters:
┌─ ├─ └─ for trees
─── for dividers}

## Principles

- {Key behavior rule}
- {Graceful degradation}
- {What to never do}

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| {wrong approach} | {correct approach} |

Spec Rules

• YAML frontmatter: name, description (one line), version, user_invocable: true
• description: one line that fits a skill listing — not a paragraph
• arguments: only if behavior genuinely changes with parameters
• Box-drawing: ┌ ├ └ ─ │ for all structured output
• Paths: ~ or $HOME, never hardcoded personal paths
• Common Mistakes: ALWAYS include, 3-6 rows minimum
• MCP pattern: Step 0 reads mcp.json → ToolSearch → degradation chain

Step 5: Preview and Location

Show the skill, then ask via AskUserQuestion:

Generated: /{skill-name}
Pattern: {A|B|C|D} — {name}
Lines: {count}
Sections: {list of ## headers}

Where to install?

1. Global (~/.claude/skills/) — available everywhere (Recommended)
2. Project (.claude/skills/) — only current directory
3. Show only — don't install yet

Step 6: Install and Verify

mkdir -p {path}/{skill-name}

Write SKILL.md with the Write tool (not bash).

Verify:

wc -l {path}/{skill-name}/SKILL.md

Step 7: Post-Install

/{skill-name} installed

  path: {full_path}/SKILL.md
  size: {lines} lines
  pattern: {A|B|C|D} — {name}

  test:  /{skill-name}
  edit:  {full_path}/SKILL.md

Quality Checklist

Validate all 7 before writing:

| # | Check | Criteria | |---|-------|----------| | 1 | Self-contained | Works without deps it can't detect | | 2 | Graceful degradation | Missing source = skip, not error | | 3 | Specific output | Exact format shown, not "generate report" | | 4 | Monospace-first | Box-drawing chars for all structure | | 5 | Tool-aware | Names which Claude Code tools to use | | 6 | Right size | 40-150 lines. Longer → split into skills | | 7 | Anonymized | ~ or $HOME, no personal paths |

Fix before preview if any check fails.

Real Examples

| User says | Skill | Pattern | Key feature | |-----------|-------|---------|-------------| | "summarize meetings and send to TG" | meeting-digest | B Pipeline | Krisp → synthesize → telegram send | | "nag me about overdue tasks" | task-nag | D Integrator | Linear → filter overdue → urgent list | | "weekly review from sessions" | weekly-review | B Pipeline | JSONL scan → topic extraction → report | | "audit my security" | security-scan | A Audit | .env, secrets, permissions → scored | | "HTML from markdown" | md-to-html | C Generator | Read .md → template → write .html | | "check vault health" | vault-health | A Audit | File count, size, orphans → scored |

Common Mistakes

| Mistake | Fix | |---------|-----| | Description > 1 line | One sentence max — must fit skill listing | | Args skill doesn't need | Only add if behavior genuinely changes | | Vague output: "nice report" | Show EXACT format with box-drawing | | No MCP degradation chain | Always: MCP → file fallback → skip | | Skill > 150 lines | Split into 2 — a skill does ONE thing | | Missing Common Mistakes | Every skill needs 3-6 rows minimum | | Not checking mcp.json first | Step 0 discovers what's available |