creating-skills

Create a New Skill

Build a new Claude Code skill through a structured workflow that ensures quality, testability, and integration with the singularity evolution engine.

Prerequisites

• Read superpowers:writing-skills if available — it defines SKILL.md authoring best practices
• This skill creates standard Claude Code skills usable by any plugin

Workflow

Step 1: Requirements Gathering

Ask the user ONE question at a time:

1. What does this skill do? (core purpose in one sentence)
2. When should it trigger? (symptoms, conditions, error messages)
3. What tools does it need? (Read, Write, Edit, Bash, Agent, etc.)
4. What's the output? (files created, code modified, analysis produced)

Step 2: Check Registry

Read ~/.claude/singularity/registry.json to verify no duplicate or overlapping skill exists.

If a similar skill exists, ask: "A skill called '' already covers . Should I extend it or create a separate skill?"

Step 3: Generate SKILL.md

Create the skill following these conventions:

---
name: <skill-name>  # kebab-case, verb-first (e.g., creating-api-clients)
description: Use when <triggering conditions>  # Max 500 chars, start with "Use when"
---

Content structure:

• Overview (1-2 sentences)
• When to use / when NOT to use
• Workflow steps (numbered, actionable)
• Common mistakes / red flags
• Integration with other skills (if applicable)

Rules:

• Description = triggering conditions ONLY, not what the skill does
• Keep under 500 words for frequently-used skills
• Use cross-references (superpowers:skill-name) not file paths
• Include a "When NOT to use" section

Step 4: Write the Skill

Write to ~/.claude/skills/<skill-name>/SKILL.md

If the skill needs supporting files (templates, rubrics, scripts), create them in: ~/.claude/skills/<skill-name>/references/

Step 5: Register

Update ~/.claude/singularity/registry.json:

# Using score-manager to initialize scoring
"${CLAUDE_PLUGIN_ROOT}/scripts/score-manager.sh" init <skill-name>

Then update registry.json to add the skill entry:

{
  "skills": {
    "<skill-name>": {
      "location": "~/.claude/skills/<skill-name>/SKILL.md",
      "createdBy": "singularity-claude:creating-skills",
      "createdAt": "<ISO-8601>",
      "currentVersion": "v1.0.0",
      "maturity": "draft",
      "tags": ["<relevant>", "<tags>"],
      "lastExecuted": null,
      "executionCount": 0,
      "averageScore": 0
    }
  }
}

Step 6: Initial Test

Invoke the newly created skill via the Skill tool to verify it loads correctly.

Step 7: Initial Score

Run singularity-claude:scoring on the test output to establish a baseline score.

Step 8: Log Telemetry

"${CLAUDE_PLUGIN_ROOT}/scripts/telemetry-writer.sh" log <skill-name> \
  --trigger "creation" \
  --summary "Created new skill: <description>"

Output

After creation, report:

• Skill location: ~/.claude/skills/<skill-name>/SKILL.md
• Initial version: v1.0.0
• Maturity: draft
• Next steps: use the skill, then score with /singularity-score