Skill Creator — Powered by Skill Seekers

Uses the Skill Seekers CLI to generate, enhance, and install SKILL.md files. After initial analysis, an impact report is presented for your approval before any pipeline steps run. Once approved, execution continues automatically until the skill is fully installed and registered.

Skill Seekers CLI — Quick Reference

pip install skill-seekers        # one-time install

skill-seekers create [URL]      # create from GitHub repo or docs URL
skill-seekers package <dir> --target claude   # package for Claude
skill-seekers enhance <dir> --level [1-5]    # AI enhancement
skill-seekers install-agent ~/.claude/skills/[name]   # install to library

Enhancement levels: 1=light polish, 2=standard (default), 3=deep, 4=comprehensive, 5=expert Enhancement modes: --mode api (Claude API) or --mode local (claude CLI, free)

Step 0: Ensure Skill Seekers Is Installed

which skill-seekers || pip3 show skill-seekers

If not present, install it automatically:

pip3 install skill-seekers

Step 1: Parse Intent and Detect Mode

Signal	Mode
`/skill-creator [URL]`	URL mode — create from GitHub repo or docs page
`/skill-creator --name [name]`	Scratch mode — scaffold from spec
`/skill-creator enhance [skill]`	Enhance mode — upgrade an existing skill
`/skill-creator --preset [name]`	Preset mode — scaffold from framework preset
No flags given	Interactive mode — ask what to create

Flag: --quality-gate off — bypasses the description quality gate (Step 6). Default: gate is on. When --quality-gate off is passed, the quality report is skipped in the final output.

Ask clarifying questions only for genuinely ambiguous intent. Infer what you can.

Step 2: Initial Analysis (No Execution Yet)

Before running anything, analyze the request and present:

## Initial Analysis

**Mode:** [URL / Scratch / Enhance / Preset / Interactive]
**Source:** [URL or "user specification"]
**Skill name:** [derived or specified]
**Target platform:** claude

**Skill Seekers will:**
1. Scrape/parse the source
2. Generate SKILL.md + references/ subdir
3. Package output for the Claude platform
4. Install to ~/.claude/skills/[name]/

**Parameters available:**
- Enhancement level: 1-5 (default: 2)
- Enhancement mode: api / local (default: api if ANTHROPIC_API_KEY set)
- Framework preset: [available presets]

Do you want to approve this, or adjust parameters first?

Wait for your approval or parameter modification before proceeding.

Step 3: Impact Analysis (Approval Gate)

After your approval, present the full impact analysis:

## Impact Analysis

**Mode:** [URL / Scratch / Enhance / Preset]
**Source:** [URL or "user specification"]
**Skill name:** [name]
**Target platform:** claude
**Framework preset:** [name or "standard"]
**Enhancement level:** [1-5]
**Enhancement mode:** [api | local]

**What will happen:**
1. skill-seekers create → [source parsed]
2. SKILL.md output → ~/.claude/skills/[name]/SKILL.md
3. references/ subdir → ~/.claude/skills/[name]/references/
4. skill lint → `skill-registry.py --lint --changed-only` on the new skill dir (no new violations)
5. skills/INDEX.md → regenerated from disk by `skill-registry.py` (generated, never hand-edited)
6. _security/ → skill queued for trust review (agent-authored tier)

**Existing skills affected:** [list only if enhance mode]
**Registry:** skills/INDEX.md regenerated (1 new skill)
**Files created:** [2-N depending on enhancement level]

Proceed? (yes / no / modify parameters)

Continue until the pipeline is done after you approve. Do not stop mid-pipeline.

Step 4: Run Skill Seekers

URL Mode

skill-seekers create "[URL]"
skill-seekers package output/$(basename "$(pwd)") --target claude

Scratch Mode

skill-seekers create \
  --name "[name]" \
  --preset standard \
  --enhance-level [level]

Enhance Mode

skill-seekers enhance ~/.claude/skills/[existing-skill] \
  --level [1-5] \
  --mode [api|local]

Preset Mode

skill-seekers create \
  --name "[name]" \
  --preset "[preset-name].json"

Default enhancement level: 2. Default mode: api if ANTHROPIC_API_KEY is set, local otherwise.

Step 5: Install to Skills Library

skill-seekers install-agent [output-dir]

Falls back if install-agent is unavailable:

mkdir -p ~/.claude/skills/[name]
cp -r [output-dir]/* ~/.claude/skills/[name]/

Step 6: Quality Gate — Rate Description Quality

Skip this step if --quality-gate off was passed in Step 1.

Run /skill-quality [name]. This:

Spawns two independent critics (Capability + Likelihood to Pick Up, 0–100 each)
Applies the calibrated gate: avg ≥ 80 AND at least one ≥ 85 AND no score < 70
On FAIL: rewrites the description automatically, then re-rates once
Writes results to skill-quality/results/[name]-quality-results.json
Returns a summary table

Collect the quality gate result. It tells you:

registration_status: "registered" (PASS) or "flagged" (failed after rewrite)

Step 7: Lint, then Register (generated INDEX.md)

Lint first. Run on the new skill dir before registering:

python3 {agency-root}/scripts/skill-registry.py --lint --changed-only {agency-root}/skills/[name]/SKILL.md

Exit 1 = new lint violation (LINT FAIL lines: body over 5k tokens or 500 lines, description + when_to_use over 400 chars, references two levels deep, hardcoded self-path, non-spec frontmatter key). STOP registration until fixed, then re-run lint. Exit 0 = continue. Custom frontmatter keys belong under metadata: with string values (lists and maps as JSON strings); never add to scripts/skill-registry/lint-baseline.json by hand to get past a failure.

skills/INDEX.md is GENERATED from the SKILL.md files on disk. Never append a row to it by hand. Regenerate it:

python3 {agency-root}/scripts/skill-registry.py          # writes skills/INDEX.md (no-op when current)
python3 {agency-root}/scripts/skill-registry.py --check  # exit 1 if it is stale

The new row's text is the skill's frontmatter description; its table is the router domain from scripts/skill-route/overlay.json. A skill with no overlay entry is listed under "Unrouted" and is left out of the router menu. Add the entry (default: hidden from the router; pass --domain D --hint H to make it routable):

python3 {agency-root}/scripts/skill-route-overlay-add.py [name]
python3 {agency-root}/scripts/skill-registry.py

Step 8: Security Gate — Quarantine Notification

Skill Seekers output is AI-enhanced (trust_level: agent-authored). Report:

⚠️ Trust review required: [name] generated by Skill Seekers.
Placed in _security/quarantine/. Human review needed before live use.
Run /cso to initiate security review.

Do not mark the skill live until the _security/ review completes.

Step 9: Report to User

If --quality-gate off was used, report:

Skill creation complete. Quality gate bypassed (--quality-gate off).

~/.claude/skills/[name]/
  SKILL.md
  references/

skills/INDEX.md — regenerated (skill-registry.py)
_quarantine/ — pending trust review

This skill is AI-enhanced. Human trust review required before live use.
Quality gate was skipped — use /skill-quality [name] to audit description quality.

Otherwise, include the quality gate result from Step 6:

Skill creation complete.

~/.claude/skills/[name]/
  SKILL.md
  references/

skills/INDEX.md — regenerated (skill-registry.py)
_quarantine/ — pending trust review
skill-quality/results/[name]-quality-results.json — written

## Quality Gate Summary
| Critic   | Capability | Likelihood | Average | Gate |
|----------|-----------|------------|---------|------|
| critic-a | [C]        | [L]        | [avg]   | [PASS/FAIL] |
| critic-b | [C]        | [L]        | [avg]   | [PASS/FAIL] |
| **Combined** | —    | —          | **[avg]** | **[✅ PASS / ❌ FAIL]** |

[If flagged:] ⚠️ Description was auto-rewritten. Run /skill-creator enhance [name] --level 4 for deeper improvement.
[If discrepancy:] ⚠️ Critics disagreed by >20 pts — see results JSON for details.

End every report (both variants above) with: New top-level skill folder: restart Claude Code (or run /reload-skills if your version has it) before it is invocable.

Common Rationalizations (Anti-Rationalization Table)

Every SKILL.md template should include a "Common Rationalizations" section. This is a first-class part of the skill definition — not an afterthought. Include it between the process steps and the Red Flags section.

Why it matters: Agents (and humans) rationalize skipping skills under pressure. Naming the rationalizations explicitly prevents them from succeeding silently.

Format:

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "This task is too small for this skill" | [counter-argument] |
| "I'll skip this step just this once" | [what that actually costs] |
| "We don't have time for this" | [what the time actually buys] |
| "[specific domain rationalization]" | [specific counter] |

Rules for the table:

4–8 rows (not fewer than 4; more than 8 dilutes signal)
Every rationalization must be a phrase someone would actually say or think — not abstract
Every reality must be concrete: name the cost, the failure mode, or the specific thing that goes wrong
Include at least one domain-specific rationalization (not just generic ones)
Write rationalizations as quotes — they sound like something a developer says

When creating or enhancing a skill, if the input skill lacks a Common Rationalizations section, add one as part of the AI enhancement pass (level 2+).

Simplify-Ignore Pattern (Locked-Section Protection)

When a skill or document contains sections that must not be modified by agents or automated tools — architecture contracts, no-touch zones, signed-off decisions — use the simplify-ignore pattern to protect them.

The pattern: mark locked sections with a content-hash placeholder so automated tools skip them while humans can still read the original content.

When to apply this pattern in skill context:

A SKILL.md contains an "Integration Contracts" or "No-Touch Zones" section that Coords must not modify
A project memory file contains a decision that is "locked" per decisions.md
A configuration section is under change control

Implementation approach (instruction-level, no hook required): Add this to the "Key Rules" section of any skill whose output includes locked content:

**Locked-section rule:** If this skill's output includes sections marked `<!-- LOCKED: [reason] -->`,
treat those sections as read-only. Do not modify, reformat, or simplify content between
`<!-- LOCKED-START -->` and `<!-- LOCKED-END -->` markers. Surface locked section presence to the
user before making any edits that could affect surrounding content.

Do NOT implement this as a hook. Hook implementation requires infrastructure management. Use HTML comment markers + instruction-level guidance in the skill that produces the output.

Skill Learnings Convention

Every new skill should support the staging → distill → promote feedback model:

Stage: After invocation, if the user gives explicit feedback (positive or negative), append a timestamped entry to {skill}/learnings-raw.md. This file is never loaded into context — it's the raw archive.
Distill: After 10+ raw entries accumulate, distill into {skill}/learnings.md (max 20 lines of principles). This replaces the previous digest. learnings.md IS loaded at invocation start if it exists.
Promote: If a principle is universally true and stable, bake it into SKILL.md directly and remove from learnings.md.

When generating a new skill, include in the SKILL.md:

A step near the start: "If learnings.md exists in this skill's directory, read it before proceeding."
A step at the end: "If the user provides feedback on this run, append a - {YYYY-MM-DD}: {insight} line to learnings-raw.md."

Key Rules

Always present impact analysis before executing — your approval is the gate
Continue until pipeline is done after approval — no stopping mid-execution
Install skill-seekers if missing — handle automatically, don't ask
Register via the generator — never create a skill without Step 7 (lint, overlay entry, then skill-registry.py); never hand-edit skills/INDEX.md
Trust level is agent-authored — Skill Seekers output triggers quarantine

skill-creator

SKILL.mdskills/skill-creator/SKILL.md