Creating a New Skill

Follow this workflow when creating a new Claude Code Skill.

0. Fetch latest best practices (REQUIRED)

Before writing any skill content, you MUST fetch and read the latest documentation:

• Skills overview: https://code.claude.com/docs/en/skills

• Best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Use WebFetch to retrieve these pages and extract key guidelines before proceeding.

1. Gather requirements

Ask the user:

• What task should this skill automate?

• What triggers should activate this skill? (keywords, file types, contexts)

• Should it be project-scoped (.claude/skills/ ) or personal (~/.claude/skills/ )?

• What tools does it need? (Read, Grep, Glob, Bash, WebFetch, Write, etc.)

2. Review existing skills for patterns

Check existing skills in the project for naming conventions and structure:

ls -la .claude/skills/

Read similar skills if they exist to maintain consistency.

3. Create skill structure

Directory structure

.claude/skills/<skill-name>/ ├── SKILL.md # Main instructions (required) ├── reference/ # Optional: detailed docs │ └── *.md └── scripts/ # Optional: utility scripts └── .py|.sh

SKILL.md format (required fields)

name: skill-name-in-kebab-case description: Brief description of what this Skill does and when to use it. Include specific trigger keywords. allowed-tools: Read, Grep, Glob # Optional: restrict tool access

Skill Title

Instructions

Clear, step-by-step guidance...

4. Apply best practices checklist

Naming

• REQUIRED: Use 1k- prefix for all OneKey project skills: 1k-date-formatting , 1k-transaction-handling

• Use gerund form after prefix: 1k-processing-pdfs , 1k-analyzing-code , 1k-creating-commits

• Max 64 chars, lowercase letters/numbers/hyphens only

• No reserved words: "anthropic", "claude"

Description

• Write in third person ("Processes...", not "I can help..." or "You can use...")

• Include what it does AND when to use it

• Include specific trigger keywords users would say

• Max 1024 chars

Content

• Keep SKILL.md body under 500 lines

• Be concise - Claude is already smart

• Use progressive disclosure: put detailed content in separate files

• Keep file references one level deep from SKILL.md

• Use Unix-style paths (forward slashes)

• Avoid time-sensitive information

Structure

• Provide concrete examples, not abstract descriptions

• Use consistent terminology throughout

• Include workflows for complex tasks

• Add validation/feedback loops for quality-critical tasks

5. Output the skill

After gathering requirements and applying best practices:

• Create the skill directory

• Write SKILL.md with proper frontmatter

• Add reference files if needed (for content > 500 lines)

• Summarize what was created

Example: Simple skill

name: 1k-generating-commit-messages description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.

Generating Commit Messages

Instructions

1. Run git diff --staged to see changes
2. Suggest a commit message with:
   • Summary under 50 characters
   • Detailed description
   • Affected components

Best practices

• Use present tense
• Explain what and why, not how

Note: All OneKey project skills MUST use the 1k- prefix in the skill name.

Anti-patterns to avoid

• Vague descriptions like "Helps with documents"

• Multiple approaches without clear defaults

• Assuming packages are installed without listing them

• Windows-style paths (
  instead of / )

• Deeply nested file references (keep one level deep)

• Over-explaining what Claude already knows