sc-skill-builder

<essential_principles>

How Skills Work

Skills are modular, filesystem-based capabilities that provide domain expertise on demand.

1. Skills Are Prompts

All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.

2. SKILL.md Is Always Loaded

When a skill is invoked, Claude reads SKILL.md. Use this guarantee:

• Essential principles go in SKILL.md (can't be skipped)
• Workflow-specific content goes in workflows/
• Reusable knowledge goes in references/

3. Router Pattern for Complex Skills

skill-name/
├── SKILL.md              # Router + principles
├── workflows/            # Step-by-step procedures (FOLLOW)
├── references/           # Domain knowledge (READ)
├── templates/            # Output structures (COPY + FILL)
└── scripts/              # Executable code (RUN)

4. Pure XML Structure

No markdown headings in skill body. Use semantic XML tags (<objective>, <quick_start>, <success_criteria>).

5. Progressive Disclosure

SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed. </essential_principles>

<quick_start>

Tooling

Initialize a new skill:

python scripts/init_skill.py my-skill-name --path /path/to/skills/

Validate a skill:

python scripts/quick_validate.py /path/to/skill-name/

Package for distribution:

python scripts/package_skill.py /path/to/skill-name/

</quick_start>

1. Create new skill
2. Audit/modify existing skill
3. Add component (workflow/reference/template/script)
4. Get guidance
5. Package skill for distribution

Wait for response before proceeding.

Progressive disclosure for option 1 (create):

• Task-execution skill → workflows/create-new-skill.md
• Domain expertise skill → workflows/create-domain-expertise-skill.md

Intent-based routing:

• "audit this skill", "check skill", "review" → workflows/audit-skill.md
• "verify content", "check if current" → workflows/verify-skill.md
• "upgrade to router" → workflows/upgrade-to-router.md

After reading the workflow, follow it exactly.

<quick_reference>

Skill Structure

Simple skill (single file):

---
name: skill-name
description: What it does and when to use it.
---

<objective>What this skill does</objective>
<quick_start>Immediate actionable guidance</quick_start>
<success_criteria>How to know it worked</success_criteria>

Complex skill (router pattern):

SKILL.md:
  <essential_principles> - Always applies
  <intake> - Question to ask
  <routing> - Maps answers to workflows

workflows/:
  <required_reading> - Which refs to load
  <process> - Steps
  <success_criteria> - Done when...

references/:
  Domain knowledge, patterns, examples

scripts/:
  Executable code Claude runs as-is

</quick_reference>

<reference_index>

Domain Knowledge

All in references/:

Structure: skill-structure.md Principles: authoring-principles.md XML Tags: use-xml-tags.md Patterns: common-patterns.md Scripts: using-scripts.md Templates: using-templates.md Validation: workflows-and-validation.md Security: api-security.md </reference_index>

<workflows_index>

Workflows

All in workflows/:

<yaml_requirements>

YAML Frontmatter

Required fields:

---
name: skill-name          # lowercase-with-hyphens, matches directory
description: ...          # What it does AND when to use it (third person)
---

Name conventions: create-*, manage-*, setup-*, generate-*, build-* </yaml_requirements>

<success_criteria> A well-structured skill:

• Has valid YAML frontmatter
• Uses pure XML structure (no markdown headings in body)
• Has essential principles inline in SKILL.md
• Routes to appropriate workflows based on user intent
• Keeps SKILL.md under 500 lines
• Asks minimal clarifying questions
• Has been tested with real usage </success_criteria>