- 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/
/ ├── SKILL.md # Update quick reference └── references/rules/ └── .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 | Feature | Guide | Key Files | |
|
|
|
|
Existing topic
|
existing.md
|
path/to/files
|
|
**
New topic
**
|
new-topic.md
|
path/to/files
|
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