new-skill

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

1. Skills overview: https://code.claude.com/docs/en/skills
2. 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.

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.)

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

```bash

ls -la .claude/skills/

```

Read similar skills if they exist to maintain consistency.

Directory structure

```

.claude/skills//

├── SKILL.md # Main instructions (required)

├── reference/ # Optional: detailed docs

│ └── *.md

└── scripts/ # Optional: utility scripts

└── .py|.sh

```

SKILL.md format (required fields)

```yaml

---

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

Clear, step-by-step guidance...

```

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

After gathering requirements and applying best practices:

1. Create the skill directory
2. Write SKILL.md with proper frontmatter
3. Add reference files if needed (for content > 500 lines)
4. Summarize what was created

```yaml

---

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

1. Run git diff --staged to see changes
2. Suggest a commit message with:

- Summary under 50 characters

- Detailed description

- Affected components

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

```

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

• 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