Mk skill creator
Dual-mode skill factory: creates new skills from natural language or audits existing skills against SKILL_SCHEMA v2.0. Session-aware — extracts context from ongoing conversations or guides discovery from scratch. Produces declarative, compaction-aware, environment-agnostic SKILL.md files. Trigger when user asks to create, build, scaffold, review, or audit a skill.From its SKILL.md
npx -y skills add devmarkpro/mk-agent-tools --skill mk-skill-creatorAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
19.3 KB, as published. Nobody here has run it
Skill Creator
The ROOT skill for skill authoring. Operates in two modes: Create (draft new skills from natural language or session context) and Review (audit existing skills against SKILL_SCHEMA v2.0). Session-aware — when invoked mid-conversation, extracts the workflow the user just performed and proposes a skill to automate it.
When to Use This Skill
Trigger when:
- User says
/mk-skill-creator, "create a new skill", "build a skill", "scaffold a skill" - User says
/mk-skill-creator create <description> - User describes automation and wants it packaged as a skill
- After a work session, user says "make this a skill", "automate this process", "I want a skill for what we just did"
- User says
/mk-skill-creator review <name>, "audit the X skill", "check if skill X follows the schema"
Do NOT trigger when:
- User wants to make a small edit to an existing skill (edit directly with Read/Edit)
- User asks how skills work conceptually (answer directly)
- User wants to create an agent, not a skill (agents go in
.claude/agents/) - User wants to list, rename, or delete skills (use Bash directly)
Prerequisites
| Requirement | Details |
|---|---|
| SKILL_SCHEMA v2.0 | ${CLAUDE_SKILL_DIR}/references/SKILL_SCHEMA.md must exist |
| Skeleton template | ${CLAUDE_SKILL_DIR}/references/skill-skeleton.md |
| Existing skills | At least 1 skill in .claude/skills/ for structural reference (optional — use skeleton if none) |
| Skill validator agent | .claude/agents/skill-validator.md (optional — skip automated validation if absent) |
Design Philosophy and Checkpoint Protocol
Read ${CLAUDE_SKILL_DIR}/references/design-philosophy.md before creating or reviewing any skill. It contains the three governing principles (Declarative over Procedural, Environment Agnosticism, User Intent Empowerment) and the checkpoint format used throughout this workflow.
Workflow — Create Mode
Phase 0: Context Detection
Determine how the skill request arrived:
Scenario A — Existing session context: The user has been working in this session (files edited, tools run, multi-turn conversation) and now asks to turn that work into a skill. Signals: "automate this", "make this a skill", "skill for what we just did", or the request references work done earlier in conversation.
Scenario B — Clean start:
The user opened a fresh session or the request has no relationship to prior conversation. Signals: /mk-skill-creator create <description>, or the request is self-contained.
Detection:
- Does the user's request reference prior conversation work? → Scenario A
- Does the conversation contain substantial prior tool use or multi-step work? → Scenario A
- Otherwise → Scenario B
Branch accordingly to Phase 1A or Phase 1B.
Also detect mode: if the request contains review or audit for an existing skill → branch to Review Mode (Phase R1).
Phase 1A: Session Context Extraction (Scenario A only)
Mine the current conversation to build a picture of what the user was doing:
Extract:
- Goal: What was the user trying to accomplish?
- Steps: What sequence of actions did they take?
- Tools used: Which built-in tools, CLIs, MCP tools, or agents were involved?
- Inputs: What data did the workflow consume?
- Outputs: What did the workflow produce?
- Pain points: What was manual, repetitive, or error-prone?
- Decisions: What judgment calls did the user make that could be codified?
Important: Extract the goals of each step, not the specific commands used. The session may have used Python, but the skill should describe the goal achieved, not prescribe Python. If the user explicitly chose a specific tool for a reason, note that reason.
Do NOT:
- Assume the entire session should become one skill — look for the repeatable core
- Copy procedural commands from the session into the skill — abstract to goals
- Guess at parts you didn't observe — flag gaps instead
→ CHECKPOINT 1A: Present the extracted workflow summary. Example:
CHECKPOINT 1 — Session Analysis
- You were [goal], working with [inputs]
- The workflow was: [3-5 goal-oriented step summary]
- Capabilities needed: [what the skill needs to be able to do]
- The repeatable part seems to be: [core workflow]
- Gap: I'm not sure about [specific uncertainty]
Next: I'll explore whether this is the right shape for a skill and fill in gaps.
→ Confirm this captures it, or correct me.
Phase 1B: Discovery (Scenario B, or after 1A to fill gaps)
Understand the problem before defining the solution. Do NOT jump to requirements.
1B.1 Understand the problem: Ask (or extract from user description — do not ask what's already clear):
- What problem does this solve? What's painful or repetitive today?
- Who invokes this — the user directly, or should Claude auto-detect the need?
- What does "done" look like? What's the output or end state?
1B.2 Validate the approach:
- Is a skill the right solution? (vs. an agent for background work, a hook for automated triggers, or a plain script)
- Does an existing skill already handle this? Check existing skills in
.claude/skills/for trigger overlap. - Is this one skill or should it be split into multiple?
1B.3 Scope the skill:
- What's the minimum viable workflow?
- What are stretch goals vs. core functionality?
1B.4 Suggest improvements: If you see opportunities to make the skill more portable, simpler, or more powerful, suggest them here. Examples:
- "You mentioned using jq for parsing — if we describe the goal instead, the skill works even without jq installed"
- "This could be two simpler skills instead of one complex one"
- "Adding an argument for the output format would make this more flexible"
→ CHECKPOINT 1B:
CHECKPOINT 1 — Discovery
- Problem: [one sentence]
- Proposed solution: A skill that [one sentence]
- Why a skill (not agent/hook/script): [reason]
- Core scope: [2-3 bullets — minimum viable workflow]
- Suggestions: [improvements, or "none"]
Next: I'll define the detailed requirements — name, triggers, inputs, outputs.
→ Confirm this direction, or redirect me.
Phase 2: Requirements Definition
Now that the problem and approach are confirmed, define the skill specification.
2.1 Define structured requirements:
| Aspect | Source |
|---|---|
| Purpose | From Phase 1 discovery/extraction |
| Name | Derive kebab-case name from purpose |
| Triggers | How would a user invoke this? (3-5 natural language + slash command) |
| Inputs | What data does it need? |
| Outputs | What does it produce? |
| Capabilities needed | What must the executing agent be able to do? (NOT which specific tools) |
2.2 Determine skill characteristics for frontmatter:
| Question | If YES |
|---|---|
| External side effects? | Add SAFETY RULE |
| Accepts arguments? | Add argument-hint |
| Should Claude never auto-invoke? | Set disable-model-invocation: true |
| Uses 3+ built-in tools consistently? | Add allowed-tools |
| Self-contained pipeline? | Set context: fork + agent: |
Read ${CLAUDE_SKILL_DIR}/references/frontmatter-reference.md for the full field decision guide.
2.3 Check: if the user requested specific tools, note them as preferences. Flag where the skill could be more environment-agnostic and suggest it. Respect the user's final decision.
2.4 Determine complexity tier:
| Tier | Steps | Heading Style |
|---|---|---|
| Simple | 3-4 | Step N: |
| Medium | 5-7 | Phase N: |
| Complex | 8+ | Phase N: with sub-steps |
| Multi-mode | Any | Phase N: per mode |
→ CHECKPOINT 2:
CHECKPOINT 2 — Skill Spec
- Name: `<name>`
- Purpose: [one sentence]
- Triggers: [slash command + 2-3 natural language variants]
- Workflow outline: [numbered goal-oriented steps, one line each]
- Capabilities: [what the agent needs to do, not which tools]
- Special: [SAFETY RULE / argument-hint / context:fork — or "none"]
- [If applicable: "You asked for X — I've included it. Note: making this tool-agnostic would improve portability."]
Next: I'll read the schema and draft the full SKILL.md.
→ Confirm this spec, or adjust.
Phase 3: Draft SKILL.md
3.1 Read the schema and skeleton template from ${CLAUDE_SKILL_DIR}/references/.
3.2 Find existing skills matching the complexity tier for structural reference.
3.3 Generate the complete SKILL.md. Key authoring rules:
- Frontmatter: All applicable fields from Phase 2.
descriptionis CSO-optimized — first 250 chars = primary use case, end with "Trigger when/with...", NEVER summarize the workflow. - H1 Title: Title Case of
name+ 1-2 sentence summary. - SAFETY RULE (conditional): Only when Phase 2 identified external side effects.
- When to Use: Triggers + anti-triggers with parenthetical redirects.
- Prerequisites: Table format. List capabilities needed, not specific tool versions. Mark optional items.
- Workflow: Each step states: the goal (what to achieve), the acceptance criteria (how to know it worked), and optionally constraints (what to avoid). Never prescribe specific tools or commands.
- Edge Cases: Table, 8-20 rows. MUST cover: missing data, tool unavailability, ambiguous input.
- Tools: Heading
## Tools. Group:Built-in (required),External CLI (optional),MCP Tools (optional),Agent. Mark everything beyond Read/Write/Edit/Bash/Grep/Glob as optional. - Examples: 5-8 triggering + 4-6 non-triggering with redirect hints.
- Success Criteria: 10-20 numbered testable assertions focused on outcomes, not process.
3.4 Declarative quality check before writing:
- Does any workflow step prescribe a specific command, language, or tool? → Rewrite as a goal
- Does any step assume a specific OS or package manager? → Make environment-agnostic
- If user requested a specific tool: is it noted as a preference, not a requirement?
- Are success criteria about outcomes ("report contains X") not process ("Python script ran")?
3.5 Compaction check before writing:
- SAFETY RULE + triggers in first ~40 lines
- Core workflow in first ~150 lines
- Total: 100-500 lines, under ~3,750 words
- Offload heavy reference material to
references/ - Use
${CLAUDE_SKILL_DIR}for all supporting file references
3.6 Write the skill files.
→ CHECKPOINT 3:
CHECKPOINT 3 — Draft Complete
- File: `.claude/skills/<name>/SKILL.md` ([N] lines, [N] words)
- Sections: [list of H2 headings present]
- Declarative check: [PASS — no procedural commands / NEEDS WORK — specific issues]
- SAFETY RULE: [included / not needed]
- Supporting files: [list, or "none"]
- Compaction: [SAFE — critical content in first N lines]
Next: I'll validate against the schema and run quality checks.
→ Review the file, then confirm. Or point out issues to fix first.
Phase 4: Validate (max 3 iterations)
4.1 If a skill-validator agent exists at .claude/agents/skill-validator.md, invoke it. Otherwise, validate manually against SKILL_SCHEMA.md — check required sections, frontmatter fields, formatting rules, and declarative compliance.
4.2 Parse the result:
- PASS (0 errors): proceed
- FAIL: apply fixes, re-validate. Maximum 3 iterations.
4.3 Additional quality checks:
- Word count: verify under ~3,750 words
- Trigger conflict check against existing skills
- Reference consistency: supporting directories match
## Reference Filessection - Declarative compliance: no procedural commands leaked into workflow steps
→ CHECKPOINT 4:
CHECKPOINT 4 — Validation
- Schema validation: PASS/FAIL ([N] errors, [N] warnings)
- Declarative compliance: PASS/FAIL
- Token budget: [N] words ([within/over] limit)
- Trigger conflicts: [none / list]
Next: I'll generate test scenarios, then present for final approval.
→ Confirm, or flag issues.
Phase 5: Simulated Conversation Test
Generate 3 test scenarios:
| # | Type | What to Check |
|---|---|---|
| 1 | Triggering prompt | Skill activates, correct workflow fires, expected output |
| 2 | Non-triggering prompt | Skill does NOT activate, correct redirect suggested |
| 3 | Edge case | Ambiguous/missing input, graceful handling per Edge Cases table |
Phase 6: Final Review
Present to the user:
- Skill summary (name, purpose, trigger, file location)
- Validation: PASS
- Simulation results table (3 rows)
- Approve, Edit, or Reject?
Phase 7: Finalize
If approved: confirm file location, suggest CLAUDE.md update if appropriate. If edit requested: apply edits → re-validate (Phase 4) → re-present (Phase 6).
Workflow — Review Mode
Phase R1: Load Target Skill
Parse skill name from arguments. Find the matching SKILL.md in .claude/skills/. Read it and the schema.
Phase R2: Automated Audit
R2.1 If a skill-validator agent exists, run it. Otherwise, validate manually against the schema.
R2.2 Run additional checks. Read ${CLAUDE_SKILL_DIR}/references/review-checklist.md for the full checklist. Key checks:
| Category | Checks |
|---|---|
| Declarative | Workflow steps describe goals, not commands? No hardcoded tools/languages? Environment-agnostic? |
| CSO Quality | Description front-loaded? No workflow summary? Trigger hint present? |
| Compaction | Under 5,000 tokens? Critical content in first 150 lines? |
| Frontmatter | No unknown fields? Missing recommended fields? |
| Structure | ## Tools heading? ${CLAUDE_SKILL_DIR} used? Phase/Step naming consistent? |
| References | ## Reference Files matches actual subdirectories? |
Phase R3: Report and Remediate
Present a structured audit report:
- Validator result (PASS/FAIL)
- Declarative compliance (procedural patterns found, with rewrites)
- CSO quality assessment
- Compaction readiness
- Structural compliance
- Specific fix suggestions
Ask: Should I apply the fixes?
If yes: apply fixes → re-validate → re-present report.
Edge Cases
| Situation | Handling |
|---|---|
| Skill name conflicts with existing skill | Show existing skill, ask user to rename or update existing |
| Trigger phrases overlap with existing skill | Flag overlap, require user to disambiguate before proceeding |
| User description too vague | Enter Discovery (Phase 1B) to explore the problem space |
| Session context is ambiguous (multiple workflows) | Ask user which part of the session to capture |
| Session had debugging/tangents mixed in | Extract only the repeatable core, flag what was excluded |
| User explicitly requests a specific tool | Accommodate the preference, suggest declarative alternative, respect user's choice |
| Produced skill contains procedural commands | Flag at CHECKPOINT 3 declarative check, rewrite as goals |
| Validation fails 3 times | Show remaining errors, ask user to manually fix or adjust requirements |
| User wants an agent, not a skill | Explain difference, offer to create agent instead |
| Skill would exceed 500 lines | Offload reference material to references/ subdirectory |
| No existing skills for reference | Use schema + skeleton template as structural guide |
| Schema file missing | Abort with clear error — schema is the source of truth |
| Review mode: skill path not found | Search by partial name, offer closest matches |
| User asks to create a skill that exists | Offer to review/update existing or create with different name |
| User confirms checkpoint but adds caveats | Incorporate the caveat, re-present same checkpoint |
| User skips ahead ("just write it") | Warn that skipping discovery risks a poor skill, but comply if user insists |
Tools
Built-in (required):
- Read — reading schema, reference skills, session context, drafts
- Write — creating SKILL.md and reference files
- Edit — applying validation fixes and declarative rewrites
- Grep — finding trigger conflicts, scanning existing skills
- Glob — finding existing skills
- Bash — directory creation, file operations
Agent (optional):
- skill-validator — automated validation in Phase 4 and Phase R2 (if
.claude/agents/skill-validator.mdexists)
Examples
Triggering Prompts
/mk-skill-creator/mk-skill-creator create weekly email summarizerCreate a new skill for weekly status reportsBuild a skill that processes API responses into reportsI want a skill that generates meeting prep briefings from my calendarCan we turn what we just did into a skill?I want to automate this process as a skill/mk-skill-creator review my-skill-nameAudit my data-pipeline skill
Non-Triggering Prompts
Edit the deploy skill to add a new phase(edit directly with Read/Edit)How do skills work in Claude Code?(answer conceptually)Create an agent for health checks(create agent in.claude/agents/)Delete the old morning-briefing skill(use Bash directly)List all my skills(use Glob or Bash directly)
Success Criteria
- Session context is correctly detected (Scenario A vs B)
- When session context exists, extracted workflow captures goals not commands
- Discovery phase explores the problem before defining the solution
- Every phase ends with a checkpoint that the user confirms
- Checkpoints are 2-5 bullets — concise, not overwhelming
- User feedback at checkpoints is incorporated before proceeding
- When user requests a specific tool, it is accommodated with alternatives suggested
- Produced skill workflow steps describe goals and acceptance criteria, not commands
- Produced skill makes no assumptions about OS, language runtime, or CLI availability
- Produced skill marks all non-built-in tools as optional
- SKILL.md is created at
.claude/skills/<name>/SKILL.md - Folder name matches
namefrontmatter field exactly - Description is CSO-optimized: first 250 chars = primary use case, ends with trigger hint
- All required sections are present in schema v2.0 order
- SAFETY RULE is included when skill has external side effects
- No trigger overlap with existing skills
- SKILL.md is 100-500 lines and under ~3,750 words
- Critical content in the first 150 lines
- User approves the final output
Reference Files
| File | Purpose |
|---|---|
references/SKILL_SCHEMA.md | The v2.0 schema — source of truth for all structural validation |
references/skill-skeleton.md | Annotated SKILL.md template with all v2.0 sections and compaction guidance |
references/frontmatter-reference.md | Full frontmatter field guide with decision trees and CSO rules |
references/review-checklist.md | Structured audit checklist for review mode |
references/design-philosophy.md | Governing principles (declarative, environment-agnostic, user intent) and checkpoint format |
examples/create-session.md | Worked example: creating a skill through all phases |