skill-create

Guide users through creating new jaan.to skills with web research and best practices.

Context Files

docs/extending/create-skill.md - Skill creation specification (v3.0.0)
$JAAN_LEARN_DIR/jaan-to-skill-create.learn.md - Past lessons (loaded in Pre-Execution)
$JAAN_TEMPLATES_DIR/jaan-to-skill-create.template.md - Generation templates
$JAAN_CONTEXT_DIR/config.md - Current skill catalog
${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol

Input

Skill Idea: $ARGUMENTS

If provided, use as starting context. Otherwise, begin with identity questions.

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: skill-create Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

v3.0.0 Common Mistakes to Avoid (regardless of LEARN.md):

✗ Using hardcoded jaan-to/outputs/ instead of $JAAN_OUTPUTS_DIR
✗ Using hardcoded jaan-to/templates/ instead of $JAAN_TEMPLATES_DIR
✗ Using hardcoded jaan-to/learn/ instead of $JAAN_LEARN_DIR
✗ Using hardcoded jaan-to/context/ instead of $JAAN_CONTEXT_DIR
✗ Forgetting #anchor syntax when importing tech.md sections
✗ Using too-broad permissions like Write(jaan-to/**)
✗ Not validating with /jaan-to:skill-update before user testing

If the file does not exist, continue without it (but still avoid mistakes above).

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_skill-create

PHASE 0: Duplicate Detection (Single Source of Truth)

Before any creation, check for existing skills:

Glob skills/*/SKILL.md to get all skills
For each skill, compare:
- Role + domain match
- Purpose description similarity
- Calculate overlap score (0-100%)
Decision tree:
- Exact match exists: "Skill '{name}' already does this. Use: /{command} [show example]"
- >70% overlap: "'{name}' is similar ({n}% overlap). Update it instead? [update/new]"
  - If update: Invoke /jaan-to:skill-update {name}
  - If new: Continue with creation
- <70% overlap: Continue with creation
Fast-track option for simple skills:

"This seems straightforward. Create minimal skill directly? [y/wizard]"

Skip wizard for:
- Single-purpose skills with obvious structure
- Skills that wrap an existing command
- Internal/utility skills with <50 lines expected

PHASE 1: Analysis (Interactive + Research)

Thinking Mode

ultrathink

Use extended reasoning for:

Analyzing user requirements
Planning skill structure
Validating against specification
Research synthesis

Questioning Guidelines

Ask up to 7 clarifying questions across Phase 1 if needed.

Skip questions when:

Information already provided in user input
Research answered the question
Context files contain the answer
Question is redundant with previous answer

Make questions smart:

Reference user's input: "You said '{X}' — does that mean...?"
Build on research: "Best practices suggest Y — does that fit your case?"
Probe specifics: "What should happen when Z?"

Step 1: Basic Identity

Ask these questions one at a time:

Question	Purpose	Validation
"What role does this skill serve?"	Determine role prefix	Must be: pm, dev, qa, ux, data, growth, or custom
"What domain/area does it work in?"	Determine domain	1-2 words, lowercase, hyphens allowed
"What action does it perform?"	Determine action verb	write, create, add, review, generate, update, analyze, etc.

After answers, validate and show:

"Skill name will be: {role}-{domain}-{action}" "Command: /jaan-to:{role}-{domain}-{action}" "Directory: skills/{role}-{domain}-{action}/"

Step 1.5: Check Project Configuration (v3.0.0)

Before proceeding with design, understand the project's configuration:

Check if configuration exists:
- Read jaan-to/config/settings.yaml (if exists)
- Note any custom path configurations
Path customization check:
- Are default paths customized?
- If settings.yaml has paths: section, note custom locations
- Skills should use $JAAN_* env vars (automatically resolve to correct paths)
Learning strategy:
- Check settings.yaml for learning.strategy: "merge" or "override"
- merge: Combine plugin + project lessons (default, recommended)
- override: Use only project lessons (ignore plugin defaults)
Template customization:
- Check if custom templates exist for similar skills
- Pattern: templates.{skill-name}.path: "./custom/path.md"
- If project has custom templates, new skill should follow same pattern

Information helps generate skills that work correctly with the project's configuration.

"Configuration checked: [default paths / custom paths detected]"

Step 2: Web Research (Token-Optimized)

Use Task tool with Explore subagent to isolate research tokens:

Task prompt: "Research best practices for {domain} {action}:
1. Search '{domain} best practices {year}'
2. Search '{domain} report template'
3. Search 'how to {action} {domain}'
4. Search '{domain} checklist'

Return:
- 3-5 key best practices
- Suggested questions the skill should ask
- Suggested quality checks
- Suggested output sections
- Sources used"

Present research summary to user:

"Research findings for {domain}:

Best Practices Found:

{practice1}

{practice2} ...

Suggested Questions for Skill:

{question1}

{question2} ...

Suggested Quality Checks:

{check1}

{check2} ...

Suggested Output Sections:

{section1}

{section2} ..."

Step 3: Purpose & Triggers

Show research-based suggestions, then ask:

"What does this skill do? (1-2 sentences)"
"What phrases should auto-trigger this skill?"
- [Suggested]: {action} {domain}, {domain} {action}, etc.

Step 4: Input & Output

"What input does the skill need?"
- Examples: file path, topic name, feature description
- Will become $ARGUMENTS handling
"What files/outputs does it produce?"
- [Suggested from templates]: {format} file with {sections}
"What format? (markdown/json/both)"
- Determines template.md creation

Step 5: Questions, Quality & Done

Present research-based suggestions, let user accept/modify/add:

"What questions should the skill ask users?"
- [Pre-filled from research]:
  - {research_question1}
  - {research_question2}
- "Add more or modify? [accept/edit]"
"What quality checks before writing?"
- [Pre-filled from research]:
  - {research_check1}
  - {research_check2}
- "Add more or modify? [accept/edit]"
"What defines 'done' for this skill?"
- [Suggested]:
  - Output file written
  - Quality checks pass
  - User approved

HARD STOP - Human Review Check

Present complete skill structure:

SKILL SUMMARY
─────────────
Name: {role}-{domain}-{action}
Command: /{role}-{domain}-{action}
Logical: {role}-{domain}-{action}
Description: {description}

RESEARCH USED
─────────────
Sources: {source_count} web sources consulted
Best practices incorporated: {practice_count}

FILES TO CREATE
───────────────
□ skills/{name}/SKILL.md
□ skills/{name}/LEARN.md
□ skills/{name}/template.md (if needed)

WILL ALSO
─────────
□ Register in scripts/seeds/config.md
□ Create docs/skills/{role}/{name}.md (via /jaan-to:docs-create)
□ Commit to branch skill/{name}

"Create this skill? [y/n/edit]"

Do NOT proceed to Phase 2 without explicit approval.

PHASE 2: Generation (Write Phase)

Step 6: Create Git Branch

git checkout dev
git pull origin dev
git checkout -b skill/{role}-{domain}-{action}

Confirm: "Created branch skill/{name} from dev. All work on this branch."

Step 7: Generate SKILL.md

Use template from $JAAN_TEMPLATES_DIR/jaan-to-skill-create.template.md:

Fill YAML frontmatter:
- name: {name}
- description: from Step 3 (must include "Use when" trigger phrase, no colons)
- allowed-tools: based on needs from Step 5
- argument-hint: from Step 4
- license: PROPRIETARY
- DO NOT add model: field (use inherited default)
Fill markdown body:
- Context Files from gathered info
- Input handling from Step 4
- Phase 1 questions from Step 5
- HARD STOP section
- Phase 2 generation steps
- Quality checks from Step 5
- Definition of Done from Step 5

Step 8: Generate LEARN.md (Plugin Source)

Create skills/{name}/LEARN.md with research insights as initial lessons. Follow the standard LEARN.md structure from docs/extending/v3-compliance-reference.md section 12.7 (Better Questions, Edge Cases, Workflow, Common Mistakes). Seed each section with relevant research findings.

Step 9: Generate template.md (Plugin Source, if needed)

Based on output format from Step 4:

Use researched report structure
Include required metadata section
Add placeholders for dynamic content

Step 10: Validate Against Specification

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/skill-create-reference.md section "Specification Validation Checklist" for the full frontmatter, body, size, trust, and budget checks.

Validate against docs/extending/create-skill.md. If any check fails, fix before preview.

Step 11: Preview All Files

Show complete content of:

SKILL.md
LEARN.md
template.md (if created)

"Write these files? [y/n]"

Step 12: Write Files (v3.0.0-Compliant)

Reference: See docs/extending/v3-compliance-reference.md section "skill-create: v3.0.0 Best Practices for Writing Skills" for full details on Steps 12.1-12.9:

12.1: Frontmatter (env var permissions, anti-patterns)

12.2: Context Files section (standard env var references)

12.3: Pre-Execution section (learning + language settings pattern)

12.4: Template references (env vars, tech imports)

12.5: Output paths (ID-based folder pattern, id-generator.sh, index-updater.sh)

12.6: template.md variable syntax ({{field}}, {{env:VAR}}, {{config:key}}, {{import:path#section}})

12.7: LEARN.md seed structure (plugin-side, merge strategy)

12.8: v3.0.0 validation checklist (compliance, output structure, tech stack, learning, quality)

12.9: Automated path scan (hardcoded path detection and auto-fix)

Write to skills/{name}/SKILL.md, skills/{name}/LEARN.md, and skills/{name}/template.md (if needed), following all v3.0.0 patterns from the reference.

Confirm: "Skill files written to skills/{name}/ (v3.0.0-compliant)"

Step 13: Tech Stack Integration (Optional)

Ask: "Should this skill reference the project's tech stack?"

Reference: See docs/extending/v3-compliance-reference.md section "skill-create: Tech Stack Integration Reference" for full details on Steps 13.1-13.4 (identifying needs, updating SKILL.md, template imports, documentation).

Tech-aware: PRD generation, code generation, story writing, API docs. Tech-agnostic: Research, non-technical docs, roadmap planning.

"Tech integration: [enabled / not applicable]"

Step 14: Update Config Catalog

Edit scripts/seeds/config.md to add skill to Available Skills table:

| {role}-{domain}-{action} | `/{name}` | {short_description} |

Step 14.5: Update Team Roles Registry

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/skill-create-reference.md section "Team Roles Registry Update Procedure" for the full role-matching and registry update steps.

If skill name matches a known role prefix, update skills/team-ship/roles.md accordingly. If roles.md does not exist, skip silently.

Step 15: Auto-Invoke Documentation

Run /jaan-to:docs-create to create:

docs/skills/{role}/{name}.md

This ensures documentation is always created with the skill.

Step 16: Commit to Branch

Reference: See docs/extending/git-pr-workflow.md section "skill-create: Commit to Branch" for the full commit template.

Before staging, run:

bash scripts/prepare-skill-pr.sh

This regenerates + validates Codex skillpack artifacts and stages adapters/codex/skillpack/.

Then stage skills/{name}/, jaan-to/, and docs/skills/{role}/{name}.md. Commit with feat(skill) message including description and research source count.

PHASE 3: Testing & PR

Step 17: Validate v3.0.0 Compliance

Run /jaan-to:skill-update {skill-name} before user testing.

Reference: See docs/extending/v3-compliance-reference.md section "skill-create: v3.0.0 Post-Creation Validation" for full validation details.

Only proceed to user testing after validation passes.

Step 18: User Testing

"Please test the skill in a new session. Here's a copy-paste ready example:"
/{name} "{example_input_based_on_skill_purpose}"
For example, if the skill is pm-prd-write:
/jaan-to:pm-prd-write "Add user authentication with OAuth support"
"Did it work correctly? [y/n]"

If issues:

Help debug the problem
Make fixes
Commit fixes
Repeat testing

Step 19: Create Pull Request

When user confirms working:

"Create pull request to merge to dev? [y/n]"

Reference: See docs/extending/git-pr-workflow.md section "skill-create: Create Pull Request" for the full gh pr create template.

Push branch, create PR with skill summary, research used, files created, and an explicit line:

Codex skillpack sync: ✅ generated via scripts/prepare-skill-pr.sh

Show PR URL to user.

If no:

"Branch skill/{name} is ready. Merge manually when ready."

Step 20: Capture Feedback

"Any feedback on the skill creation process? [y/n]"

If yes:

Run /jaan-to:learn-add skill-create "{feedback}"

Step 21: Auto-Invoke Roadmap Update

Run /jaan-to:pm-roadmap-update to sync the new skill with the roadmap.

This ensures the roadmap reflects the latest skill additions.

Skill Alignment

Two-phase workflow with HARD STOP for human approval
Single source of truth (no duplication)
Plugin-internal automation
Maintains human control over changes

skill-create

skill-create

Context Files

Input

Pre-Execution Protocol

Language Settings

PHASE 0: Duplicate Detection (Single Source of Truth)

PHASE 1: Analysis (Interactive + Research)

Thinking Mode

Questioning Guidelines

Step 1: Basic Identity

Step 1.5: Check Project Configuration (v3.0.0)

Step 2: Web Research (Token-Optimized)

Step 3: Purpose & Triggers

Step 4: Input & Output

Step 5: Questions, Quality & Done

HARD STOP - Human Review Check

PHASE 2: Generation (Write Phase)

Step 6: Create Git Branch

Step 7: Generate SKILL.md

Step 8: Generate LEARN.md (Plugin Source)

Step 9: Generate template.md (Plugin Source, if needed)

Step 10: Validate Against Specification

Step 11: Preview All Files

Step 12: Write Files (v3.0.0-Compliant)

Step 13: Tech Stack Integration (Optional)

Step 14: Update Config Catalog

Step 14.5: Update Team Roles Registry

Step 15: Auto-Invoke Documentation

Step 16: Commit to Branch

PHASE 3: Testing & PR

Step 17: Validate v3.0.0 Compliance

Step 18: User Testing

Step 19: Create Pull Request

Step 20: Capture Feedback

Step 21: Auto-Invoke Roadmap Update

Skill Alignment

Definition of Done