Skill Factory

Create custom Claude Code skills and install them into the local hideki-plugins marketplace in one workflow.

Workflow

Gather requirements — Understand what the skill should do
Design the skill — Plan structure, references, scripts, assets
Team orchestration assessment — Decide if the skill needs multi-agent review; if so, select perspectives
Create skill files and install — Write SKILL.md, supporting resources, then always install immediately
Verify — Confirm the skill appears in a new session

Step 1: Gather Requirements

Ask the user:

What should the skill do? Get 2-3 concrete usage examples.
What triggers it? (e.g., "review PR", "create diagram")
Does it need external tools? (gh CLI, APIs, MCP servers)
What output format? (markdown report, file creation, GitHub actions)

Keep it to 2-3 focused questions max. Skip if the user already provided enough detail.

Formalize as BDD scenarios

After gathering requirements, write 3-5 Given/When/Then scenarios covering:

Primary use case
One or two secondary paths
An edge case (missing info, invalid input)

Read references/bdd-skill-scenarios.md for templates by skill type and anti-patterns.

Step 2: Design the Skill

Read references/skill-design-guide.md for design patterns and structure guidance.

Decide:

Freedom level: High (text guidance) vs Low (exact scripts)
References needed? Detailed checklists, schemas, examples → put in references/
Scripts needed? Deterministic operations → put in scripts/
Assets needed? Templates, images → put in assets/
Scenario mapping: Map each BDD scenario to SKILL.md sections (trigger context → frontmatter, workflow → body, outputs → format/references)

Step 3: Team Orchestration Assessment

Determine whether the skill being created should have a built-in multi-agent team review step in its own workflow.

Quick Assessment

Evaluate the target skill against these criteria:

Does it have a multi-phase workflow where design decisions affect later phases?
Does it touch cross-cutting concerns (security, performance, architecture)?
Would multiple stakeholder perspectives improve its output quality?
Does it modify code, infrastructure, or shared resources?
Could wrong output from this skill cause significant rework?

If 2+ criteria are true → the skill should include team orchestration. Proceed to the detailed design below. If 0-1 → skip team orchestration for this skill. Proceed to Step 4.

Design Team Perspectives (only when assessment warrants it)

Read references/skill-design-review-team.md for the full perspective catalog with prompts, output formats, and cross-skill delegation notes.

From the catalog, select which perspectives apply to the target skill. Include in the target skill's SKILL.md:

The sentence: "Create an agent team to explore this from different angles: [selected perspectives]"
A reference file under the target skill's references/ with the detailed teammate prompts for the selected perspectives

Do NOT copy all perspectives — only include the ones relevant to the target skill's domain.

Step 4: Create Skill Files

Create the skill directory at D:\Shared\agents\my-skills\<skill-name>\.

SKILL.md frontmatter

---
name: <skill-name>
description: <What it does + ALL trigger phrases. This is the only text Claude sees before loading the skill body.>
---

The description is critical — it controls when the skill triggers. Include:

What the skill does (1 sentence)
All contexts/scenarios when to use it
Specific trigger phrases

SKILL.md body

Use imperative form
Keep under 500 lines
Only include knowledge Claude doesn't already have
Reference any references/ files with clear "read this when..." guidance
Include a ## Behavior Scenarios section with the Given/When/Then specs from Step 1

Supporting files

Place in subdirectories as needed:

references/ — Loaded by Claude on demand
scripts/ — Executed directly
assets/ — Used in output, not loaded into context

Install into marketplace

Always run the install script immediately after creating or updating skill files. Do not ask the user — just install.

python "D:\Shared\agents\my-skills\my-skill-factory\scripts\install_skill.py" "D:\Shared\agents\my-skills\<skill-name>"

For a specific version:

python "D:\Shared\agents\my-skills\my-skill-factory\scripts\install_skill.py" "D:\Shared\agents\my-skills\<skill-name>" --version 1.1.0

The script handles everything:

Creates marketplace plugin structure under my-marketplace/plugins/<name>/
Registers in root marketplace.json
Caches to ~/.claude/plugins/cache/hideki-plugins/<name>/<version>/
Adds entry to installed_plugins.json
Enables in settings.json

Read references/marketplace-structure.md for full details on the file layout and JSON schemas.

Commit and push

Always commit and push immediately after installing. Do not ask the user — just do it.

cd D:\Shared\agents\my-skills
git add <skill-name>/ my-marketplace/plugins/<skill-name>/ my-marketplace/.claude-plugin/marketplace.json
git commit -m "feat: add <skill-name> skill"
git push

Step 5: Verify

Launch a new CLI session to confirm:

echo "List all available skills. Just list the skill names as a bullet list." | claude -p

The new skill should appear as <skill-name>:<skill-name> in the output.

Updating an Existing Skill

Write scenarios for the change — Define Given/When/Then scenarios for new or modified behavior
Identify the delta — Compare new scenarios against existing ones; classify as Added, Modified, or Removed
Team assessment — Re-evaluate if the updated skill should add, remove, or change team perspectives
Edit skill files and install — Update SKILL.md and supporting files, then always run the install script immediately (it overwrites the previous installation)
Commit and push — git add the skill source dir, marketplace plugin dir, and marketplace.json, then git commit -m "chore: update <skill-name> skill" and git push
Validate coverage — Confirm each new scenario has corresponding content in SKILL.md
Verify — New sessions will pick up the changes automatically

Behavior Scenarios

Scenario: Create a new skill from scratch
  Given the user has a clear idea for a new skill
  When the user says "create a skill for X"
  Then the skill gathers requirements, writes BDD scenarios, designs structure,
       assesses whether team orchestration is needed, includes team perspectives
       if warranted, creates files, installs, commits and pushes, and verifies

Scenario: Skill assessed as needing team orchestration
  Given the user wants a skill with a multi-phase workflow touching security and architecture
  When the assessment finds 2+ criteria are true
  Then the skill includes a "Create an agent team..." step with selected perspectives
       and a references file with detailed teammate prompts

Scenario: Skill assessed as NOT needing team orchestration
  Given the user wants a simple single-step utility skill
  When the assessment finds 0-1 criteria are true
  Then team orchestration is skipped and no team review step is included in the skill

Scenario: Update an existing skill
  Given a skill is already installed in the marketplace
  When the user says "update the X skill to add Y"
  Then the skill writes change-delta scenarios, identifies added/modified/removed behaviors, edits files, always re-installs immediately without asking, commits and pushes, and verifies

Scenario: Vague request
  Given the user provides only a one-line idea without details
  When the user says "make me a skill"
  Then the skill asks 2-3 focused questions to clarify purpose, triggers, and output format

Scenario: Skill with external dependencies
  Given the user needs a skill that relies on CLI tools or MCP servers
  When the user describes the skill's requirements
  Then the skill identifies dependencies, documents them in SKILL.md, and includes setup guidance

Scenario: Re-install without changes
  Given a skill's files have not changed
  When the user re-runs the install script
  Then the script overwrites the previous installation and the skill remains functional

References

references/skill-design-guide.md — Quick reference for skill structure, freedom levels, patterns, and what to include/exclude
references/bdd-skill-scenarios.md — Given/When/Then templates by skill type, update-delta guidance, and anti-patterns
references/marketplace-structure.md — Full directory layout, JSON schemas, and config file locations for the local marketplace
references/skill-design-review-team.md — Perspective catalog: available team angles, prompts, output formats, and cross-skill delegation (loaded only when assessment warrants team orchestration)