Skill Designer

Purpose

This meta-skill provides patterns, templates, and checklists for creating high-quality skills within AWS Coworker. Use this skill when designing new skills from conversations, requirements, or identified gaps.

When to Use

• •Creating a new skill for AWS Coworker
• •Reviewing or improving an existing skill
• •Converting repeated conversation patterns into reusable skills
• •Extending AWS Coworker's capabilities

When NOT to Use

• •Creating slash commands (use command-designer instead)
• •Modifying agent definitions (follow agent patterns directly)
• •One-off tasks that don't warrant a reusable skill

Skill Design Process

Step 1: Identify the Need

Before creating a skill, answer:

1. •

   What gap does this fill?

   • •What task or pattern is not covered by existing skills?
   • •Has this come up multiple times in conversations?
2. •

   Who will use it?

   • •Which agents should have access to this skill?
   • •What level of AWS expertise is assumed?
3. •

   What's the scope?

   • •Is it focused enough to be useful?
   • •Is it broad enough to justify a separate skill?

Step 2: Determine Category

Step 3: Choose a Name

Naming Convention: {category-prefix}-{descriptive-name}

Good names:

• •aws-cli-playbook — Clear, describes content
• •aws-governance-guardrails — Indicates purpose
• •skill-designer — Action-oriented

Avoid:

• •misc-utils — Too vague
• •my-aws-skill — Not descriptive
• •skill1 — Not meaningful

Step 4: Write the Skill

Follow this template:

---
name: skill-name
description: One-line description (max 100 chars)
version: 1.0.0
category: aws|org|meta|core
agents: [list, of, compatible, agents]
tools: [Read, Write, Bash, etc]
---

# Skill Name

## Purpose

[2-3 sentences explaining why this skill exists and what problem it solves]

## When to Use

- [Specific scenario 1]
- [Specific scenario 2]
- [Specific scenario 3]

## When NOT to Use

- [Anti-pattern or exclusion 1]
- [Anti-pattern or exclusion 2]

---

## Guidance

### [Section 1: Primary Content]

[Main instructions, patterns, or reference material]

### [Section 2: Additional Content]

[Supporting information, examples, edge cases]

---

## Examples

### Example 1: [Scenario]

[Concrete example with inputs and expected outputs]

### Example 2: [Scenario]

[Another example showing different usage]

---

## Related Skills

- `skill-name-1` — [How it relates]
- `skill-name-2` — [How it relates]

Frontmatter Reference

Required Fields

Optional Fields

Quality Checklist

Before finalizing a skill, verify:

Structure

• • Valid YAML frontmatter
• • All required fields present
• • Consistent heading hierarchy
• • Proper markdown formatting

Content

• • Clear, specific purpose statement
• • Actionable "When to Use" scenarios
• • Helpful "When NOT to Use" exclusions
• • Substantive guidance section
• • At least one concrete example

Naming

• • Follows naming convention
• • Unique (no conflicts with existing skills)
• • Descriptive and memorable

Integration

• • Compatible agents listed correctly
• • Required tools accurately specified
• • Related skills cross-referenced

Documentation

• • README updated if user-facing
• • CHANGELOG entry added
• • Examples tested and working

Supporting Files

Skills may include supporting files:

skills/aws/my-skill/
├── SKILL.md           # Required: main skill definition
├── templates/         # Optional: reusable templates
│   └── resource.yaml
├── examples/          # Optional: detailed examples
│   ├── basic.md
│   └── advanced.md
└── commands/          # Optional: sub-command references
    └── service1.md

When to Add Supporting Files

• •Templates: Reusable configuration or code snippets
• •Examples: Complex scenarios needing detailed walkthroughs
• •Commands: Service-specific command references (for large skills)

Common Patterns

Pattern 1: Service-Specific AWS Skill

For skills covering a specific AWS service:

## Discovery Commands

[Read-only commands to explore current state]

## Common Operations

[Frequently used patterns with examples]

## Safety Considerations

[What to watch out for, common mistakes]

## IaC Patterns

[CDK/Terraform/CloudFormation approaches]

Pattern 2: Governance/Policy Skill

For skills encoding rules and constraints:

## Always Do

[Mandatory practices]

## Never Do

[Prohibited actions]

## Validation Checks

[How to verify compliance]

## Exceptions Process

[How to handle legitimate exceptions]

Pattern 3: Workflow Skill

For skills describing multi-step processes:

## Prerequisites

[What must be in place before starting]

## Step-by-Step Process

[Numbered steps with checkpoints]

## Validation

[How to verify success]

## Rollback

[How to undo if needed]

Anti-Patterns

Avoid these common mistakes:

Too Broad

❌ "AWS Best Practices" — covers everything, helps nothing

✅ "AWS S3 Security Patterns" — focused, actionable

Too Narrow

❌ "How to Create One Specific Lambda" — too specific

✅ "AWS Lambda Deployment Patterns" — reusable across scenarios

Missing Context

❌ Just commands without explanation

✅ Commands with rationale, prerequisites, and expected outcomes

Copy-Paste Documentation

❌ Verbatim AWS docs (adds no value)

✅ Curated, opinionated guidance based on AWS docs

Iteration and Improvement

Skills should evolve:

1. •Initial version: Cover core use cases
2. •Refinement: Add examples based on real usage
3. •Expansion: Include edge cases and advanced patterns
4. •Consolidation: Merge or split as scope clarifies

Use /aws-coworker-audit-library to identify skills needing improvement.