jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/plugins/cc-architect/workflows/create-skill.md

5.7 KiB
Raw Permalink Blame History

Workflow: Create Skill

Model tier: Haiku (research/scaffold), Sonnet (processing/content), Opus (synthesis), Haiku (cleanup)

When to use

  • Creating a new skill for a project or plugin
  • The skill doesn't exist yet or needs to be rebuilt from scratch

Before you start

If concept unclear, brainstorm: references/brainstorming/workflow.md

Inputs required

  • target_location - .claude/skills/<skill-name>/ (project) or <plugin-path>/skills/<skill-name>/ (plugin)
  • skill_name - kebab-case
  • skill_purpose - What problem this solves
  • initial_workflows - At least one task to handle

Task document

Create: .claude/plugin-data/skill-architect/tasks/new-skill-<skill-name>-<date>.md All subagents append to this.

Pattern consideration

See references/tool-patterns/catalog.md.

Question If Yes
Will skill make design decisions? Include brainstorming triggers
Will skill modify files? Include verification step
Will skill create files in user projects? Follow plugin-data-convention
Will skill need maintenance/auditing? Create reversion protection scaffolding
Will skill orchestrate 2+ subagent workflows with synthesis? Use Role-Workflow pattern

Phases

Phase 1: Research (Haiku)

Objective: Gather requirements, validate inputs, design structure, scaffold files.

Read:

  • ${CLAUDE_PLUGIN_ROOT}/references/layout/reference.md
  • references/tool-patterns/deterministic-scripting.md
  • ${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md

Do:

  1. Clarify with user: skill purpose, major workflows, knowledge domains
  2. Map workflows to workflows/*.md
  3. Map knowledge domains to references/ subdirs
  4. Identify scripting opportunities (mechanical, repeatable, unambiguous?)
  5. Identify scripts vs templates vs knowledge docs
  6. Write to task doc: ## Domain Understanding, ## Proposed Structure, ## Script Candidates
  7. Confirm with user (checkpoint)
  8. Scaffold skill directory tree by hand, following ${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md:
    • Omit target-dir or use "project" for .claude/skills/<skill-name>/
    • Create: SKILL.md (empty stub), workflows/, references/, and templates//scripts/ if the skill needs them
    • Create empty reference.md in each references subdir
    • Reversion protection: invariants.md (stub), examples/golden/, .decisions/
  9. Write to task doc: ## Scaffolded Files

Invariants stub:

# Invariants
Behaviors that must not change without explicit human approval.
> TODO: Fill after skill stabilizes (2-3 uses). See `references/tool-patterns/reversion-protection.md`.
## Critical Invariants
- [To be defined]
## Structural Invariants
- [To be defined]

Outputs: Task document with domain understanding, structure plan, scaffolded files.

Phase 2: Processing (Sonnet)

Objective: Write workflows, reference.md files, knowledge docs, scripts, and templates.

Read:

  • Task document (all sections from Phase 1)
  • ${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md
  • references/progressive-disclosure/reference-md-pattern.md

Do:

  1. Write workflows:

    • One workflows/<workflow-name>.md per workflow
    • Include: when to use, inputs, subtasks with subagent hints, task doc instructions
    • Pattern hooks: brainstorming reference (if design decisions), verification step (if modifies files)
    • Write to task doc: ## Workflows Written

  2. Write reference.md files:

    • For each references subdir: write reference.md
    • Include: purpose, what's here, when to read which file, model hints
    • Stub knowledge docs
    • Write to task doc: ## Reference.md Files Created

  3. Fill knowledge docs:

    • Write each knowledge doc, <=150 lines
    • If longer, split and update parent reference.md
    • May require user input for domain expertise
    • Write to task doc: ## Knowledge Docs Written

  4. Create scripts and templates:

    • Write scripts for mechanical tasks
    • Write templates for repetitive structures
    • Make scripts executable
    • Write to task doc: ## Scripts and Templates Created

Outputs: Complete workflow files, reference.md navigation, knowledge docs, scripts, templates.

Phase 3: Synthesis (Opus + Haiku cleanup)

Objective: Write SKILL.md, validate, generate description, final review.

Subagent: Opus for decisions, then Haiku for cleanup.

Read:

  • Task document (complete)
  • ${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md
  • All created workflow files (spot-check)

Do (Opus):

  1. Inline vs Reference decision:
    • Count workflow content lines (exclude blanks, frontmatter, headings)
    • Threshold: <=40 (inline full), 41-100 (inline checklist + reference), >100 (reference only)
    • Multiple workflows -> router pattern
  2. Generate description via the generate-description workflow (${CLAUDE_PLUGIN_ROOT}/workflows/generate-description.md):
    • Input: type=skill, name, purpose, triggers
  3. Write SKILL.md with description, applying inline vs reference decision
  4. Write to task doc: ## SKILL.md Structure Decision
  5. Validate against ${CLAUDE_PLUGIN_ROOT}/templates/audit-checklist-template.md (Skill-Specific Attributes section)
  6. Fix validation errors
  7. Verify structure matches plan
  8. Verify reference.md files accurate
  9. Friction? Add to task doc: ## Friction / Improvement Notes
  10. Write final summary

Do (Haiku cleanup):

  1. Remove task document artifacts
  2. Verify all placeholder text filled
  3. Final file permissions check (scripts executable)

Outputs: Complete, validated skill with SKILL.md, ready for use.