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. Check if skill should merge into existing skill (REQUIRED)

Before creating a new skill, first check if the content belongs in an existing skill.

Review existing skills

ls -la .claude/skills/

Decision criteria for merging

MERGE into existing skill as a rule if:

• Topic is closely related to an existing skill's domain

• Content would be a sub-topic of an existing skill

• Similar workflows or patterns already exist

• Adding as a rule keeps related knowledge together

CREATE new skill if:

• Topic is distinct and doesn't fit any existing category

• Content is substantial enough to warrant standalone skill

• Different trigger keywords and use cases

• Would make existing skill too large or unfocused

Token optimization considerations

When to split existing skills:

Skills should be split when they become too large, causing unnecessary token consumption on every load. Use these criteria:

🚨 SPLIT if any of these apply:

• File size: Reference file >10 KB or >1000 lines

• Usage frequency mismatch: Topics used in very different scenarios

• Independent workflows: Topics don't share common patterns

• Specific trigger words: Topic has distinct keywords that rarely overlap

✅ KEEP TOGETHER if:

• High correlation: Topics frequently used together (>50% overlap)

• Shared concepts: Common patterns, terminology, or workflows

• Small files: All reference files <5 KB each

• Natural grouping: User thinks of topics as related

Token savings formula:

Token Savings = (Skill_Size × Probability_Not_Needed) - Split_Overhead

Where:

• Skill_Size: Total tokens in skill (SKILL.md + all references)
• Probability_Not_Needed: % of tasks that don't need this topic
• Split_Overhead: ~500-1000 tokens (new SKILL.md + metadata)

Real-world examples from our codebase:

Original Size Split Into Token Savings

1k-coding-patterns

15 KB (9 files) 6 focused skills 47-53% in 90% cases

1k-dev-workflows

43 KB (3 files) 3 focused skills 80% when not doing Sentry

Splitting strategies:

Conservative split (safe, minimal disruption):

• Split only the largest, most independent file

• Keep related topics together

• Example: Split 34 KB Sentry analysis from 43 KB workflows

Moderate split (balanced):

• Split 3-5 distinct topics into separate skills

• Keep core patterns together

• Example: Split date, i18n, error-handling, cross-platform, code-quality

Aggressive split (maximum optimization):

• Each major topic becomes its own skill

• Only keep truly inseparable content together

• Use when: Very large skill (>50 KB), low topic correlation

Existing skill categories for OneKey

Category Skill Merge candidates

Analytics/Tracking 1k-analytics

Event tracking, Mixpanel, LogToServer, defaultLogger

Architecture 1k-architecture

Project structure, import rules

Code quality 1k-code-quality

Lint fixes, pre-commit tasks, documentation

Code review 1k-code-review-pr

PR review checklists

Coding patterns 1k-coding-patterns

React patterns, TypeScript conventions

Create PR 1k-create-pr

PR creation workflow

Cross-platform 1k-cross-platform

Platform-specific code

Date formatting 1k-date-formatting

Date/time display, locale formatting

DeFi integration 1k-defi-module-integration

Staking, lending, Earn, Borrow modules

Dev commands 1k-dev-commands

Build, test, lint commands

Error handling 1k-error-handling

Try/catch, error boundaries, user-facing errors

Feature development 1k-feature-guides

New chains, socket events, notifications, pages, routes

Git workflow 1k-git-workflow

Branching, commits, PRs

Group think 1k-group-think

Multi-agent collaborative analysis

i18n 1k-i18n

Translations, locales

Monitor PR CI 1k-monitor-pr-ci

CI check monitoring, PR status

Native module patches 1k-patching-native-modules

iOS/Android crash fixes, native code patches

Package upgrades 1k-pkg-upgrade-review

Dependency upgrade review, compatibility

Performance 1k-performance

Optimization, concurrent requests, memoization

Platform requirements 1k-platform-requirements

Min SDK/OS versions for all platforms

Retrospective 1k-retrospective

Bug fix analysis, checklist updates

Sentry analysis 1k-sentry-analysis

Crash reports, AppHang, ANR fixes

Sentry config 1k-sentry

Error filtering, crash configuration

State management 1k-state-management

Jotai atoms, global state

Test versions 1k-app-upgrade-test

App auto-update testing, version migration

UI recipes 1k-ui-recipes

Scroll offset, view transitions, keyboard avoidance

Merging workflow

If merging into existing skill:

Add as a rule file:

.claude/skills/<existing-skill>/ ├── SKILL.md # Update quick reference └── references/rules/ └── <new-topic>.md # Add detailed content here

Update the main SKILL.md:

• Add entry to quick reference table

• Add brief summary section

• Link to the new rule file

Example merge:

Quick Reference

Splitting workflow

If splitting an existing skill:

Analyze current skill:

Check file sizes

ls -lh .claude/skills/<skill-name>/references/rules/ wc -l .claude/skills/<skill-name>/references/rules/*.md

Identify split candidates:

• Files >10 KB or >1000 lines

• Topics with distinct trigger words

• Workflows used independently

Create new skill directories:

mkdir -p .claude/skills/<new-skill-1>/references/rules mkdir -p .claude/skills/<new-skill-2>/references/rules

Move files (git tracks as rename):

mv .claude/skills/<old-skill>/references/rules/<topic>.md
.claude/skills/<new-skill>/references/rules/

Create SKILL.md for each new skill:

• Write focused description with specific trigger words

• Add Quick Reference section

• Include Related Skills section

Update original skill SKILL.md:

• Remove split topics from Quick Reference

• Update Related Skills to point to new skills

Update cross-references:

Find all skills that reference the old skill

grep -r "old-skill" .claude/skills/*/SKILL.md

Update each reference to point to appropriate new skill

Commit with clear message:

git add -A .claude/skills/ git commit -m "refactor: split <old-skill> into focused skills"

2. Gather requirements (for new skills)

If creating a new skill, 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.)

3. Create skill structure

Standard structure (recommended for OneKey skills)

.claude/skills/1k-<skill-name>/ ├── SKILL.md # Main entry with quick reference (required) └── references/ └── rules/ ├── topic-1.md # Detailed guide for topic 1 ├── topic-2.md # Detailed guide for topic 2 └── topic-3.md # Detailed guide for topic 3

Simple structure (for single-topic skills)

.claude/skills/1k-<skill-name>/ └── SKILL.md # All content in one file

SKILL.md template

name: 1k-skill-name 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

Brief overview.

Quick Reference

Topic 1 Summary

See: references/rules/topic-1.md

Key points:

• Point 1
• Point 2

Topic 2 Summary

See: references/rules/topic-2.md

Key points:

• Point 1
• Point 2

Related Skills

• /1k-related-skill-1 - Description
• /1k-related-skill-2 - Description

4. Apply best practices checklist

Naming

• REQUIRED: Use 1k- prefix for all OneKey project skills

• Use descriptive name: 1k-feature-guides , 1k-dev-workflows , 1k-sentry

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

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

Description

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

• Include what it does AND when to use it

• Include specific trigger keywords users would say

• Max 1024 chars

Content structure

• Main SKILL.md has quick reference table linking to rules

• Detailed content goes in references/rules/*.md

• Each rule file is self-contained and focused

• Keep SKILL.md body under 500 lines

• Use Unix-style paths (forward slashes)

Organization

• Group related topics into one skill with multiple rules

• Use consistent formatting across all rules

• Include "Related Skills" section for cross-references

• Add checklist for complex workflows

5. Output the skill

After gathering requirements and applying best practices:

• Create the skill directory with references/rules/ structure

• Write SKILL.md with quick reference table

• Add rule files for each topic

• Summarize what was created

• Run token analysis to verify optimization (REQUIRED)

Token Analysis (Self-Check)

ALWAYS run after creating or modifying skills:

Run token analysis

python3 development/skills-analysis/analyze-skills-tokens.py --sort-by-size

Check your new skill's token count

python3 development/skills-analysis/analyze-skills-tokens.py --detailed | grep -A 5 "your-skill-name"

Verification checklist:

• New skill is <5,000 tokens (ideal)

• If >5,000 tokens: Topics are highly correlated (>50% usage together)

• If >10,000 tokens: Plan immediate split

• SKILL.md has Quick Reference (avoid forcing full file load)

• No duplicate content across skills

Action based on results:

Token Count Action

< 2,000 ✅ Excellent - proceed

2,000 - 5,000 ✅ Good - proceed, monitor growth

5,000 - 10,000 ⚠️ Review: Can topics be split? If highly correlated, proceed with Quick Reference

10,000 🚨 Split before committing

See development/skills-analysis/SKILLS-TOKEN-MONITORING.md for detailed guidance.

Example: Skill with multiple rules

.claude/skills/1k-feature-guides/ ├── SKILL.md └── references/rules/ ├── adding-chains.md ├── adding-socket-events.md ├── notification-system.md └── page-and-route.md

SKILL.md content:

name: 1k-feature-guides description: Feature development guides for OneKey. Use when adding new chains, socket events, notifications, pages, or routes.

Feature Development Guides

Quick Reference

Adding New Chains

See: references/rules/adding-chains.md

Key steps:

1. Implement chain core logic
2. Add chain configuration
3. Update UI components

Anti-patterns to avoid

Structure & Organization

• ❌ Creating new skill when content fits existing category

• ❌ Putting all content in SKILL.md (use references/rules for detail)

• ❌ Deeply nested file references (keep one level deep)

• ❌ Forgetting 1k- prefix for OneKey skills

Content Quality

• ❌ Vague descriptions like "Helps with documents"

• ❌ Multiple approaches without clear defaults

• ❌ Over-explaining what Claude already knows

• ❌ Missing trigger keywords in description

Token Optimization Anti-patterns

• ❌ Keeping bloated skills: Not splitting when files exceed 10 KB

• ❌ Over-splitting: Creating separate skills for highly correlated topics

• ❌ Ignoring usage patterns: Not considering which topics are used together

• ❌ Vague trigger words: Using generic triggers that cause unnecessary loading

• ❌ No Quick Reference: Forcing full file load instead of showing summary first

• ❌ Duplicate content: Copying content across skills instead of cross-referencing

Examples of Good vs Bad Splitting

❌ BAD: Over-splitting

1k-date-format-display 1k-date-format-parse 1k-date-format-locale

Problem: These are always used together, split overhead > savings

✅ GOOD: Focused skill

1k-date-formatting ├── SKILL.md (Quick Reference) └── references/rules/date-formatting.md

❌ BAD: Keeping bloated

1k-coding-patterns (15 KB, 9 unrelated files)

Problem: Loading all patterns even when only need one

✅ GOOD: Split by independence

1k-coding-patterns (core patterns only) 1k-date-formatting (independent utility) 1k-i18n (independent utility) 1k-error-handling (independent patterns)