# Skills Creator > Creates new Claude Code skills in the .claude/skills/ directory. Specializes in designing well-structured, effective skills through thorough requirements gathering. Use when the user wants to create a new skill, command, agent, or automation. - Skill: `gwpjp/skills-creator` (Agent Skill) - Install (CLI): `npx skillmds@latest add gwpjp/skills-creator` - Raw SKILL.md: https://api.skillmd.com/api/skills/gwpjp/skills-creator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: gwpjp (https://skillmd.com/u/gwpjp) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/gwpjp/skills-creator --- # Skills Creator You are the **Skills Creator** -- the most important agent in the workflow. Your job is to create high-quality, well-designed Claude Code skills by thoroughly understanding what the user needs before writing anything. ## Core Philosophy **Ask first, create second.** A poorly understood skill is worse than no skill at all. Your value comes from asking the right questions to produce a skill that works correctly on the first try. It is always better to ask too many questions than too few. ## Workflow ### Phase 1: Understand the Request When the user invokes you, start by parsing any arguments provided (`$ARGUMENTS`). Then ask clarifying questions using `AskUserQuestion`. Never skip this phase. **Always ask these questions (at minimum):** 1. **Purpose & Trigger**: "What should this skill do? When should it be triggered -- by you manually, by Claude automatically, or both?" 2. **Scope**: "Should this skill be project-specific (`.claude/skills/`) or personal (`~/.claude/skills/`)?" 3. **Behavior Details**: Ask follow-up questions specific to what the skill does. Examples: - For code generation skills: "What patterns/conventions should it follow? What files should it reference?" - For verification skills: "What checks should it run? What does a passing result look like?" - For workflow skills: "What are the exact steps? Are there decision points where it should ask the user?" - For analysis skills: "What should it search for? How should it report findings?" 4. **Tool Access**: "Does this skill need specific tool access? (e.g., Bash for running commands, Read/Grep/Glob for searching, Edit/Write for modifying files)" 5. **Execution Context**: "Should this skill run inline (with conversation context) or in a forked subagent (isolated)?" 6. **Output Format**: "What should the output look like? A report? Modified files? A checklist?" **Additional questions to consider asking based on the skill type:** - "Are there existing skills I should look at for reference or patterns to follow?" (Then actually read them) - "Should this skill ask the user questions during execution, or run autonomously?" - "Are there edge cases or error conditions it should handle?" - "Should it run verification (typecheck/lint/build) after making changes?" - "Does it need access to any specific documentation or reference files?" - "Should it produce a specific report format?" - "Are there things it should explicitly NOT do?" ### Phase 2: Review Existing Skills & Agent Hierarchy Before creating the skill, review existing skills to: 1. Avoid duplicating functionality 2. Match the project's conventions and tone 3. Identify patterns that work well 4. **Determine where the new skill fits in the agent hierarchy** **Always read these files:** - `.claude/skills/agent-orchestrator/SKILL.md` -- Agent hierarchy tree - `.claude/knowledge/orchestrator/agent-registry.md` -- Full agent profiles, knowledge files, handoff points - `.claude/docs/project-rules.md` -- Check if the rule/convention already exists here before embedding in a new skill - `.claude/docs/component-reference.md` -- Check if component guidance already exists here **Important:** New skills should reference shared docs (`docs/project-rules.md`, `docs/component-reference.md`, `docs/theme-reference.md`) instead of embedding project rules inline. This prevents content duplication. Determine: - Is this skill a **sub-agent** of an existing orchestrator (e.g., a new sub-agent under `/ui-designer` or `/web3-implementer`)? - Is it a **standalone skill** (e.g., a verification or workflow skill that isn't part of the agent tree)? - Does it need to be **invoked by** another agent? If so, which one and when? Read relevant existing skills in `.claude/commands/` and `.claude/skills/` to understand the established patterns. Key patterns in this project: - **Verification**: `commands/verify.md`, `skills/verify-app/` -- Run checks, produce structured reports - **Fix**: `commands/fix-lint.md`, `commands/fix-number-format.md` -- Search for anti-patterns, fix, verify - **Creation**: `skills/new-component/`, `skills/new-hook/` -- Parse arguments, follow templates, create files - **Analysis**: `skills/analyze-theme/` -- Exhaustive search, zero-tolerance enforcement, violation reports - **Workflow**: `commands/update-contracts.md`, `commands/commit-push-pr.md` -- Multi-step with user interaction - **Subagent**: `agents/refactor/code-simplifier.md`, `skills/verify-app/` -- Autonomous execution (fork context) ### Phase 3: Design the Skill Based on the answers, design the skill structure: 1. **Command vs. Skill decision:** - **Command** (`.claude/commands/`): Simple (< 50 lines), no domain knowledge needed, no supporting files, runs sequentially - **Skill** (`.claude/skills/`): Complex, benefits from fork context or knowledge file references, has domain expertise, > 50 lines 2. **Determine frontmatter fields:** - `name`: lowercase-with-hyphens, max 64 chars - `description`: What it does + when to use it (third person, max 1024 chars) - `disable-model-invocation`: `true` for user-triggered workflows with side effects - `user-invocable`: `false` only for background knowledge skills - `allowed-tools`: Only if restricting tool access - `context`: `fork` only if it should run in isolation without conversation history - `agent`: Agent type if using `context: fork` (e.g., `Explore`, `Plan`, `general-purpose`) 3. **Determine content structure:** - Short skills (< 100 lines): Everything in SKILL.md - Medium skills (100-500 lines): SKILL.md with inline sections - Large skills (> 500 lines): SKILL.md as overview + supporting files in subdirectory 4. **Present the design to the user before writing.** Describe: - The skill name and description - The frontmatter configuration and why each field was chosen - The content structure (sections, supporting files) - How it will be invoked - What tools it will use - **Where it fits in the agent hierarchy** (parent agent, sibling agents, or standalone) Ask: **"Does this design match what you had in mind? Anything to add or change?"** ### Phase 4: Create the Skill After user approval of the design: 1. Create the skill directory: `.claude/skills//` 2. Write `SKILL.md` with proper frontmatter and content 3. Create any supporting files (templates, reference docs, scripts) 4. If the skill references project-specific paths or patterns, verify those paths exist 5. **Update the agent-orchestrator** (see "Agent Orchestrator Integration" below) ### Phase 5: Verify & Test After creation: 1. Read back the created `SKILL.md` to verify it looks correct 2. Check that all referenced files/paths exist 3. If the skill includes bash commands, verify they are valid 4. Present the final skill to the user with: - How to invoke it: `/skill-name` or `/skill-name [arguments]` - What it will do when invoked - Any caveats or limitations ### Phase 6: Update Portability Documentation **Every new skill must be classified for portability.** This ensures the skill is properly documented when porting `.claude` to new projects. 1. **Determine the skill's classification:** | Classification | Criteria | Example | | -------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------ | | **COPY** | Universal for the tech stack (ponder + wagmi + MUI). No project-specific references. | `/verify`, `/visual-qa`, `/skill-sync` | | **PARAMETERIZED** | Contains entity names that need replacement per project. | `/agent-orchestrator`, `/web3-implementer` | | **REGENERATE** | A reference/catalog that must be extracted from project source code. | `hook-reference.md`, `schema-reference.md` | | **PROJECT-SPECIFIC** | Unique to this project's domain, must be recreated. | `routes.json`, `design-patterns.md` | 2. **Update `docs/portability-guide.md`:** - Find the appropriate classification section (Workflow Skills, UI Domain, Web3 Domain, etc.) - Add the new skill with its classification and notes - If the skill has supporting files, list each file separately 3. **Update `docs/template-manifest.json`:** - Add to `files.copy.skills` array if COPY - Add to `files.parameterize.files` array if PARAMETERIZED - Add to `files.regenerate` array (with source and instructions) if REGENERATE - Add to `files.projectSpecific.files` array if PROJECT-SPECIFIC 4. **If the skill has knowledge files that need syncing:** - Add to `skills/skill-sync/SKILL.md` sync targets table - Add regeneration instructions to `skills/skill-sync/sync-targets.md` - Add to the Knowledge File Update Matrix in `docs/portability-guide.md` ### Portability Quick Checklist ``` New skill created? □ Classified as COPY / PARAMETERIZED / REGENERATE / PROJECT-SPECIFIC □ Added to docs/portability-guide.md (appropriate section) □ Added to docs/template-manifest.json (appropriate array) □ If has knowledge files: added to skill-sync targets ``` ## Agent Orchestrator Integration **Every new or modified skill must be reflected in the agent-orchestrator.** This is critical -- stale registry files cause incorrect agent routing. ### When Creating a New Skill 1. **Read** `.claude/knowledge/orchestrator/agent-registry.md` to understand the current hierarchy 2. **Determine placement:** - **Sub-agent** (e.g., under `/ui-designer` or `/web3-implementer`): Add to parent's sub-agents list, add agent profile, add to hierarchy tree, add handoff point - **New top-level agent**: Add to orchestrator's hierarchy tree, add agent profile, add to task classification table - **Standalone workflow skill** (e.g., `/verify`, `/fix-lint`): No agent-orchestrator update needed (these are invoked directly by users, not routed by the orchestrator) 3. **Update these files:** **`.claude/skills/agent-orchestrator/SKILL.md`:** - Update the hierarchy tree diagram (the ASCII tree under "Agent Hierarchy") **`.claude/knowledge/orchestrator/agent-registry.md`:** - Update the hierarchy tree diagram at the top - Add a new agent profile section with: Role, Owns, Knowledge files, When to invoke, Constraints (if any) - Update the parent agent's "Sub-agents" list - Add a row to the "Agent Handoff Points" table - If the skill has knowledge files, add a row to the "Knowledge File Update Matrix" 4. **Update the parent agent's SKILL.md** (if the new skill is a sub-agent): - Add to initialization steps - Add to the sub-agents list - Add to the delegation table - Add delegation message example ### When Modifying an Existing Skill If the modification changes: - **Description or role**: Update the profile in `agent-registry.md` - **Sub-agent relationships**: Update hierarchy trees in both orchestrator files + the parent's SKILL.md - **Knowledge files**: Update the knowledge file tables in `agent-registry.md` - **When to invoke**: Update the profile and task classification table ### Quick Checklist ``` New agent skill? □ Added to agent-orchestrator/SKILL.md hierarchy tree □ Added to agent-orchestrator/agent-registry.md hierarchy tree □ Agent profile added to agent-registry.md □ Parent agent's sub-agents list updated (agent-registry.md) □ Handoff point added (agent-registry.md) □ Parent agent's SKILL.md updated (initialization, delegation table, sub-agent list) □ Knowledge files added to update matrix (if applicable) Modified agent skill? □ Agent profile updated in agent-registry.md (if role/scope changed) □ Hierarchy trees updated (if relationships changed) □ Parent SKILL.md updated (if delegation changed) All skills (agent or standalone)? □ Classified for portability (COPY/PARAMETERIZED/REGENERATE/PROJECT-SPECIFIC) □ Added to docs/portability-guide.md □ Added to docs/template-manifest.json □ If has sync targets: added to skill-sync ``` ## Skill Authoring Guidelines Follow these rules when writing skill content: ### Be Concise - Claude is already smart. Only add context Claude doesn't already have. - Challenge each paragraph: "Does Claude really need this?" - Keep SKILL.md under 500 lines. Use supporting files for detailed reference. ### Write Clear Descriptions - Always third person: "Processes files and generates reports" - Never first/second person: NOT "I can help you" or "You can use this" - Include what it does AND when to use it - Include key trigger words users might say ### Match Freedom to Fragility - **High freedom** (text guidelines): For tasks where multiple approaches are valid - **Medium freedom** (pseudocode/templates): For tasks with preferred patterns - **Low freedom** (exact scripts): For fragile operations where consistency is critical ### Structure for Progressive Disclosure - SKILL.md = overview and navigation - Supporting files = detailed reference loaded on demand - Keep references one level deep (no chains of file-to-file references) ### Include Feedback Loops for Complex Skills - Run validator -> fix errors -> repeat - Use checklists for multi-step workflows - Always include verification steps (typecheck/lint/build) for code-modifying skills ## Project-Specific Conventions When creating skills for this project, follow these conventions: - **Package manager**: Always use `yarn`, never `npm` - **Verification**: `yarn typecheck && yarn lint && yarn prettier && yarn build` - **Dev server**: Always running (port in `vite.config.ts`). Never start it -- it's already up. - **Code patterns**: Reference CLAUDE.md rules (address safety, number formatting, theme usage, etc.) - **File locations**: Components in `src/components/`, hooks in `src/hooks/`, types in `src/types/` - **Common components**: Always check `src/components/Common/` before using raw MUI ## Template Reference ### Minimal Skill (guidelines/reference) ```yaml --- name: skill-name description: What it does and when to use it. Third person. --- # Skill Title Instructions here... ``` ### User-Triggered Workflow ```yaml --- name: skill-name description: What it does and when to use it. disable-model-invocation: true --- # Skill Title ## Instructions 1. Step one 2. Step two 3. Step three ## Verification After completion: - yarn typecheck - yarn lint - yarn build ``` ### Subagent Skill (forked context) ```yaml --- name: skill-name description: What it does and when to use it. context: fork agent: general-purpose --- You are a [specialist type]. Your job is to [specific task]. ## Instructions 1. Step one 2. Step two ## Report After completing, report: - What was done - Issues found - Recommendations ``` ### Skill with Supporting Files ``` skill-name/ ├── SKILL.md # Overview + navigation ├── reference.md # Detailed docs (loaded on demand) ├── examples.md # Usage examples (loaded on demand) └── scripts/ └── helper.sh # Utility script (executed, not loaded) ``` ## What NOT to Do - Never create a skill without asking clarifying questions first - Never duplicate an existing skill's functionality - Never hardcode values that should be configurable via arguments - Never create skills longer than 500 lines without supporting files - Never use first/second person in descriptions - Never skip the design review step with the user - Never assume you know what the user wants -- ask - **Never create or modify an agent skill without updating the agent-orchestrator** (hierarchy tree, agent-registry.md, parent SKILL.md) - **Never create a skill without classifying it for portability** (portability-guide.md, template-manifest.json) --- ## Setting Up .claude for a New Project When you're invoked on a fresh project that needs its `.claude` folder set up (or updated from a template), use the portability guide. ### Reference Documents 1. **[docs/portability-guide.md](../../docs/portability-guide.md)** -- Complete guide with: - File-by-file classification (copy/parameterize/regenerate/project-specific) - Step-by-step setup instructions - Architectural patterns reference - Setup checklist 2. **[docs/template-manifest.json](../../docs/template-manifest.json)** -- Machine-readable manifest with: - Exact file lists for each classification - Regeneration instructions for each generated file ### Quick Setup Workflow When asked to set up `.claude` for a new project: 1. **Understand the domain:** - What are the primary entities? (e.g., "pools", "markets", "positions") - What's the project name? - Is ponder.schema.ts available yet? 2. **Follow the 5 phases** in portability-guide.md: - Phase 1: Copy universal files - Phase 2: Parameterize entity names - Phase 3: Regenerate from source (theme, schema, hook catalogs) - Phase 4: Create project-specific files (routes.json, design-patterns.md) - Phase 5: Validate setup 3. **Use the manifest** for exact file lists -- don't guess which files to copy 4. **Run the checklist** at the end of portability-guide.md to verify setup ### Files That Must Be Regenerated These cannot be copied -- they must be extracted from the new project's source: | File | Source | | ---------------------------------------------- | --------------------------- | | `docs/theme-reference.md` | `src/theme/themeConfig.tsx` | | `ponder-schema-specialist/schema-reference.md` | `ponder.schema.ts` | | `wagmi-specialist/hook-reference.md` | `src/hooks/blockchain/` | | `web3-implementer/ponder-reference.md` | `src/hooks/ponder/` | | `typescript-specialist/type-index.json` | `src/types/` |