Skill Factory

Skill Factory

Batch-author complete custom Cowork skill packages — SKILL.md plus optional references/, scripts/, and assets/ folders — to a rigorous quality bar, with pre-write template study, tiered structure selection, and post-write verification.

When to Use

• User wants to create one or more new custom skills with supporting files
• User specifies a tier (Standard, Enhanced, Full Package) or needs guidance picking one
• User asks for a "skill package" with references, scripts, or assets
• User provides a batch list of skills to generate in a single request
• User wants skills authored against an explicit quality bar (trigger phrases, tables, troubleshooting rows)

When NOT to Use

• Simple single-skill creation with no supporting files → use the built-in skills skill
• Editing or tuning an existing skill → use skills
• Deleting or auditing existing skills → use skills
• Editing personal instructions (copilot-instructions.md) → use skills
• Writing non-skill documents (Word, PDF, Excel) → use the corresponding document skill

Quick Start

User: "Create 3 full-package skills: project-retrospective, executive-brief, quarterly-planning."

Steps:

1. Study templates — read 3–4 built-in skills at /opt/workspace-config/.claude/skills/ and the legal-redliner gold-standard at /mnt/user-config/.claude/skills/legal-redliner/
2. Check capacity — confirm new skills fit under the 50-skill limit
3. Validate names — ensure kebab-case, no shadowing of built-in names
4. Draft each package — SKILL.md first, then references/scripts/assets per tier
5. Write files — mkdir -p the skill directory, then Write each file
6. Verify — Glob the skill directory and confirm every declared file exists
7. Report — tell the user what was created and that OneDrive sync lands in ~35 seconds

Paths & Sync

OneDrive visibility: Files written to /mnt/user-config/.claude/skills/{name}/ appear in the user's OneDrive under Cowork/Skills/{name}/ after ~35 seconds (rclone flush + blob replication).

Limit: 50 skills maximum. Each SKILL.md must stay under 1 MB.

Tier Selection

If the user does not specify a tier, propose one based on scope — recommend Enhanced for any skill needing frameworks like ADKAR/RACI/RAID, and Full Package when the skill has deterministic computation or verbatim template content.

See references/component-spec.md for exact sizing rules per component.

Authoring Workflow

Phase 1 — Study (MANDATORY before writing)

Before drafting anything, read these references to absorb the house style:

1. 3–4 built-in skills at /opt/workspace-config/.claude/skills/ — e.g. calendar-management/SKILL.md, daily-briefing/SKILL.md, meeting-intel/SKILL.md, stakeholder-comms/SKILL.md
2. Legal-redliner at /mnt/user-config/.claude/skills/legal-redliner/ — the gold-standard Full Package with references, scripts, and assets all cross-linked
3. Templates at /opt/workspace-config/.claude/skills/skills/references/templates.md

Extract and mirror:

• YAML frontmatter shape (name, multi-line description, optional cowork: block)
• Section ordering (Overview/When to Use/When NOT/Quick Start/Core Instructions/Guardrails/Common Issues)
• Table patterns, trigger-phrase density, tone

Phase 2 — Plan Each Skill

For every skill in the batch, capture:

Phase 3 — Draft SKILL.md

Every SKILL.md must contain these sections in order:

1. YAML frontmatter — name, multi-line description with all triggers plus "Do NOT use for…" exclusions, optional cowork: block
2. H1 title matching the skill's human name
3. When to Use — bullet list of concrete trigger situations
4. When NOT to Use — bullet list with delegation to other skills
5. Quick Start — one example end-to-end workflow
6. Core Instructions / Workflow — detailed steps with tables, templates, or frameworks
7. Built-In Skills Used — table mapping each built-in skill to how it's used
8. Output Deliverables — table mapping each deliverable to a file skill (docx/xlsx/pptx/pdf) or inline render
9. Guardrails — hard rules as bullet list
10. Common Issues — troubleshooting table with ≥6 rows

Target 200–400 lines of Markdown. See references/quality-rubric.md for scoring.

Phase 4 — Author Supporting Files (Enhanced / Full Package)

Only for tiers that include them — skip for Standard.

references/ (Enhanced and above)

• Dense lookup tables, scoring algorithms, classification frameworks, heuristics
• 80–200 lines per file
• Loaded on-demand by the skill
• Link from SKILL.md with [name](references/file.md) using relative paths

scripts/ (Full Package only)

• Pure Python 3, standard library only
• Deterministic processing that should run as code, not AI (text segmentation, data extraction, scoring engines)
• Structured JSON output to stdout
• 150–400 lines per file
• Reference from SKILL.md via python scripts/filename.py <args>

assets/ (Full Package only)

• Static templates and pre-approved content inserted verbatim at runtime
• Never AI-generated at runtime — stored literal content only
• Use [PLACEHOLDER_NAME] syntax for variable substitution
• 10–150 lines per file
• Link from SKILL.md with [name](assets/file.md)

See assets/cover-note-template.md for a ready-to-reuse cover-note template and assets/checklist-template.md for a pre-write QA checklist.

Phase 5 — Write

For each skill in the batch:

mkdir -p /mnt/user-config/.claude/skills/{name}/references /mnt/user-config/.claude/skills/{name}/scripts /mnt/user-config/.claude/skills/{name}/assets

(Omit subfolders that aren't required for the tier.)

Use the Write tool — not echo or cat heredocs — to create each file. Writes must be idempotent: if re-running the batch, confirm before overwriting.

Phase 6 — Verify (DELIVERY GATE)

After writing, for every skill in the batch:

Glob /mnt/user-config/.claude/skills/{name}/**/*

Confirm:

• SKILL.md present
• Every references/*.md declared in SKILL.md exists
• Every scripts/*.py referenced exists
• Every assets/*.md referenced exists
• No broken relative links in SKILL.md

If any file is missing, investigate and re-write before reporting success. Never tell the user "done" before Glob confirms the files.

Phase 7 — Report

Tell the user in plain language:

• What was created (bulleted list with name + one-line description + tier)
• OneDrive sync timing (~35 seconds)
• How to test (invoke with a trigger phrase from the description)

Quality Bar

Every skill produced by this factory must meet these thresholds:

See references/quality-rubric.md for the full scoring breakdown.

Built-In Skills Used

Output Format

This factory does not produce docx/xlsx/pptx/pdf — it produces Markdown + Python source files for the skill runtime.

Guardrails

• Never modify built-in skills: /opt/workspace-config/.claude/skills/ is read-only
• Never fabricate frameworks: Only cite established frameworks (ADKAR, Kotter, 5 Whys, RACI, RAID, OKR, MoSCoW, SWOT, PESTLE, etc.) — if unsure, omit or use deep-research to verify
• Always study templates first: Never write a skill without reading at least 3 built-in skills in the current session
• Verify before reporting success: Glob the output directory after writing — missing files must block the success message
• Kebab-case names only: ^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$, no shadowing of built-ins (pdf, docx, xlsx, pptx, skills, calendar-management, meeting-intel, stakeholder-comms, daily-briefing, schedule-meeting, deep-reasoning, render-ui)
• Respect the 50-skill limit: Count existing skills before creating; if the batch would exceed the limit, inform the user and ask what to remove
• All calculations via code: Any scoring, counting, or percentage in a generated skill must route to code tools — never instruct the AI to do mental arithmetic
• Cross-link every file: If references/foo.md exists but SKILL.md doesn't link to it, it is dead weight — either link or delete
• Plain language in descriptions: Use outcome-oriented trigger phrases ("summarize my week") not implementation details ("calls SearchM365 with keyword filter")

Common Issues