codyswanngt/parity-skill-creator

Skill Creator

Author a new, working Lisa skill (and its pass-through command) from a one-line description. This is the Lisa-native equivalent of the upstream skill-creator@claude-plugins-official plugin, reimplemented from scratch against Lisa's conventions so the same capability is available to the Codex, agy, and Copilot runtimes (Cursor reads .claude-plugin/ natively).

Not drift-trackable

This skill intentionally carries no synced-from pin. The upstream skill-creator plugin publishes no semver (its cache version resolves to unknown), so a @unknown pin would be unparseable and meaningless to scripts/plugin-parity-drift.mjs. Drift is tracked manually — re-review the upstream plugin by hand whenever the curated plugin set is refreshed. Do not add a synced-from line to skills generated by this skill unless they reimplement a semver-versioned upstream plugin.

When to use

• A reusable workflow, checklist, or piece of domain knowledge keeps recurring and deserves a named, invokable skill.
• You are reimplementing an upstream third-party plugin command/skill for cross-agent parity (see analyze-plugin / implement-plugin-parity).
• The user asks to "create a skill", "add a command", or "scaffold a skill".

If the knowledge is narrow or one-off, prefer a rule in .claude/rules/ instead — skills are for broad, repeatable capabilities. When unsure whether content warrants a skill, run it past the skill-evaluator agent first.

Where skills live

Lisa skills are build output for downstream projects. The source of truth is plugins/src/, never the generated plugins/lisa* artifacts:

| Source directory | Builds artifact | Use for | | --- | --- | --- | | plugins/src/base/ | plugins/lisa | Skills that ship to every stack | | plugins/src/<stack>/ | plugins/lisa-<stack> | Stack-specific (typescript, expo, nestjs, cdk, harper-fabric, rails) |

Lisa-repo-only skills (parity tooling, wiki ingestion, lisa-* meta-skills) live at the root .claude/skills/ and .claude/commands/, NOT under plugins/src — they are not relevant to downstream projects. Decide placement first:

• Ships to downstream projects → plugins/src/base/skills/<name>/SKILL.md
• Only meaningful inside the Lisa monorepo → .claude/skills/<name>/SKILL.md

Naming

• Use hyphen-separated names: git-commit, tracker-write, parity-sentry-seer. No spaces, no camelCase, no underscores.
• The directory name, the frontmatter name, and the command filename must all match exactly.
• Commands map to colon-separated UI names via directory nesting: commands/git/commit.md → /lisa:git:commit; a flat commands/plan.md → /lisa:plan.

SKILL.md frontmatter

Skills support only these frontmatter keys (they do not support argument-hint or $ARGUMENTS substitution — those belong on the command):

---
name: my-skill                       # required — matches the directory name
description: "One or two sentences."  # required — when to use + what it does
allowed-tools: ["Read", "Edit", "Write", "Bash"]  # optional — least privilege
synced-from: <plugin>@<marketplace>@<version>      # ONLY for semver upstream reimplementations
---

• name — the hyphen identifier, byte-identical to the directory.
• description — write it so the model knows when to reach for the skill, not just what it does. Lead with the trigger. This is the single most important field for discoverability.
• allowed-tools — grant the minimum set. A read-only review skill needs no Write/Edit. Omit the key entirely to inherit the caller's tools.
• synced-from — add only when the skill reimplements an upstream plugin that publishes a real semver. Grammar: name@marketplace@version (e.g. sentry@[email protected]). Omit for upstreams with no semver (note that in the body instead, as this skill does).

The command pass-through pattern

Every skill should have a thin command that is the user-facing entry point. Commands support description, argument-hint, and $ARGUMENTS; they delegate straight to the skill:

---
description: "Same human-facing summary as the skill, phrased for the picker."
argument-hint: "<what the user should type after the command>"
---

Use the /lisa:my-skill skill to <do the thing>. $ARGUMENTS

The command carries the argument-hint and forwards $ARGUMENTS; the SKILL.md carries the actual logic. Keep the two descriptions consistent.

Scaffolding walkthrough

1. Decide placement — downstream (plugins/src/base) vs. Lisa-only (.claude). For base, both a skill and a command directory entry are needed.
2. Pick the name — hyphenated, unique. Check it does not collide: ls plugins/src/base/skills/ and ls plugins/src/base/commands/.
3. Create the skill at plugins/src/base/skills/<name>/SKILL.md with the frontmatter above and a body that follows house style — see plugins/src/base/skills/quality-review/SKILL.md for the canonical shape (title, "When to use", numbered checklist/steps, explicit "Rules"/"Output" sections). Write real, actionable guidance, not TODOs.
4. Create the command at plugins/src/base/commands/<name>.md (or a nested commands/<namespace>/<name>.md for a colon-namespaced command) using the pass-through template.
5. Rebuild the artifacts so the generated plugins match source:

   bun run build:plugins
   

   Then commit both plugins/src/... and the regenerated plugins/lisa*. The 🧩 Plugins Sync CI check (and bun run check:plugins locally) fails if artifacts drift from source — never hand-edit plugins/lisa*.
6. Verify discoverability — confirm the skill appears in the skill list and the command resolves to /lisa:<name>.

Body house style

• Open with an # H1 title in Title Case.
• Add a ## When to use section that names the triggers.
• Use numbered steps for procedures, checklists for review-style skills.
• End with an explicit ## Rules (hard constraints) and/or ## Output section.
• Write in plain, imperative English. Prefer concrete examples over abstraction.
• Reference sibling skills by their hyphen name (e.g. "delegate to git-commit").

Rules

• Never edit plugins/lisa* directly — edit plugins/src/ and rebuild.
• Skill frontmatter must not contain argument-hint or $ARGUMENTS.
• The directory name, name field, and command filename must match exactly.
• Add synced-from only for semver-versioned upstream reimplementations.
• Do not include /coding-philosophy in task skills metadata — it auto-loads.
• One skill, one responsibility. If a skill grows two jobs, split it.