/skill-creator-plus

Skill Creation Process

Detailed guide for each step of skill creation.

Overview

0. Route by skill archetype
1. Understand the skill with concrete examples
2. Plan reusable skill contents (scripts, references, assets)
3. Initialize the skill when a starter is useful (run init_skill.py)
4. Edit the skill (implement resources and write SKILL.md)
5. Package the skill (run package_skill.py)
6. Iterate based on real usage

Step 0: Route by Skill Archetype

Before writing, check whether the skill fits one primary category. Skills that straddle several categories often become confusing.

If the candidate does not fit one category, split it or choose another primitive before adding scope.

Source inspiration: Anthropic, "Lessons from building Claude Code: how we use skills" - https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

Step 1: Understanding with Concrete Examples

To create an effective skill, clearly understand concrete examples of how the skill will be used.

Questions to ask:

• "What functionality should this skill support?"
• "Can you give some examples of how this skill would be used?"
• "What would a user say that should trigger this skill?"

Tip: Avoid asking too many questions in a single message. Start with the most important questions.

Step 2: Planning Reusable Contents

Analyze each example by:

1. Considering how to execute from scratch
2. Identifying helpful scripts, references, and assets
3. Capturing the non-obvious gotchas that caused past failures
4. Deciding how the skill will verify success, especially for UI, CLI, deployment, or data workflows

Examples:

Prefer code or structured files when they reduce repeated reasoning:

• scripts/ for deterministic steps, assertions, or reusable fetch helpers
• references/ for gotchas, schemas, command maps, and usage patterns
• assets/ for templates, starter files, or reusable output shapes
• config.json when the skill needs user-specific setup such as channels, environments, or default destinations
• append-only logs when previous runs are part of the workflow contract, such as standups or recurring reports
• named skill dependencies only when another installed skill owns a separate responsibility; include a fallback if it may be missing

Step 3: Initializing the Skill

Before creating a self-authored Skill, confirm the target license profile and display attribution. CC BY-NC-SA 4.0 is a candidate, not an implicit CLI default. Preserve upstream license and notice evidence for third-party or derivative work.

Run init_skill.py for new skills:

scripts/init_skill.py <skill-name> --path <output-directory> \
	--license-profile cc-by-nc-sa-4.0 --author-attribution "Example Author"

The script creates a minimal self-authored target:

• Generates SKILL.md, LICENSE.txt, and skill-license.json
• Requires an explicit target profile and display attribution
• Creates no Python or placeholder resource files unless requested

Use --with-python-helper only when the target needs a Python helper. Use --with-resources only when starter reference and asset folders are useful. The initializer does not import third-party or derivative material; preserve its provenance and notices manually before packaging.

Step 4: Edit the Skill

Design Patterns

Consult these guides:

• Multi-step processes: See workflows.md
• Output formats: See output-patterns.md

Implement Resources

1. Start with scripts, references, assets identified in Step 2
2. Test scripts by running them
3. Delete unused example files

Write SKILL.md

Frontmatter:

---
name: skill-name
description: "What it does. Use when [trigger conditions]."
---

Body: Write instructions using imperative/infinitive form.

Step 5: Packaging

scripts/package_skill.py <path/to/skill-folder>
# Optional: specify output directory
scripts/package_skill.py <path/to/skill-folder> ./dist

Use packaging only when producing a distributable .skill archive. It is not required for a natural-language-only Skill authoring pass.

The script:

1. Validates - YAML format, naming, structure, description quality
2. Packages - Creates .skill file (zip with .skill extension)

Step 6: Iterate

Iteration workflow:

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify needed updates
4. Implement changes and test again

When updating, prefer adding one precise gotcha or one verification helper over broad reminders. The strongest skill updates usually come from observed misses, not generic best practices.

For skills where routing quality matters, optionally track lightweight usage signals:

• manual invocation vs model-triggered invocation
• expected-but-not-triggered cases
• success, fallback, or abandoned outcome
• description or ## When to Use phrase that needs adjustment

Keep logs append-only and minimal. Do not store full prompts, secrets, personal data, customer data, or machine-specific paths.