@tech-leads-club/agent-skills 0.1.0-beta.2

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: skill-creator
+description: Guide for creating effective AI agent skills. Use when users want to create a new skill (or update an existing skill) that extends an AI agent's capabilities with specialized knowledge, workflows, or tool integrations. Works with any agent that supports the SKILL.md format (Claude Code, Cursor, Roo, Cline, Windsurf, etc.). Triggers on "create skill", "new skill", "package knowledge", "skill for".
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective, agent-agnostic skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend AI agent capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform a general-purpose agent into a specialized agent equipped with procedural knowledge.
+
+### What Skills Provide
+
+1. **Specialized workflows** - Multi-step procedures for specific domains
+2. **Tool integrations** - Instructions for working with specific file formats or APIs
+3. **Domain expertise** - Company-specific knowledge, schemas, business logic
+4. **Bundled resources** - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share context with everything else the agent needs.
+
+**Default assumption: The agent is already very smart.** Only add context it doesn't already have. Challenge each piece of information: "Does the agent really need this?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields read to determine when the skill gets used—be clear and comprehensive.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers.
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic
+
+##### References (`references/`)
+
+Documentation and reference material loaded as needed into context.
+
+- **When to include**: For documentation the agent should reference while working
+- **Examples**: `references/schema.md` for database schemas, `references/api_docs.md` for API specifications
+- **Benefits**: Keeps SKILL.md lean, loaded only when needed
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but used within output.
+
+- **When to include**: When the skill needs files for final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/template.html` for HTML boilerplate
+
+### Progressive Disclosure
+
+Skills use a three-level loading system:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed (unlimited)
+
+Keep SKILL.md body under 500 lines. Split content into separate files when approaching this limit.
+
+## Skill Creation Process
+
+### Step 1: Understand the Skill
+
+Clarify with concrete examples:
+
+- "What functionality should this skill support?"
+- "Can you give examples of how this skill would be used?"
+- "What would trigger this skill?"
+
+### Step 2: Plan Reusable Contents
+
+Analyze each example:
+
+1. Consider how to execute from scratch
+2. Identify helpful scripts, references, and assets
+
+### Step 3: Create the Skill
+
+Create the skill directory:
+
+```
+skill-name/
+├── SKILL.md
+├── scripts/     (if needed)
+├── references/  (if needed)
+└── assets/      (if needed)
+```
+
+### Step 4: Write SKILL.md
+
+#### Frontmatter
+
+```yaml
+---
+name: skill-name
+description: What the skill does and when to use it. Include specific triggers and contexts. Max 1024 characters.
+---
+```
+
+**Description guidelines:**
+- Include both what the skill does AND when to use it
+- Include trigger phrases
+- Max 1024 characters, no XML tags
+- Write in third person
+
+#### Body
+
+Write instructions for using the skill. Include:
+- Quick start guide
+- Step-by-step workflow
+- Links to reference files when needed
+
+### Step 5: Test and Iterate
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Update SKILL.md or resources accordingly
+4. Test again
+
+## Quality Checklist
+
+Before finalizing:
+
+- [ ] Description is specific about when to use (max 1024 chars)
+- [ ] Folder name uses kebab-case
+- [ ] Instructions are actionable and unambiguous
+- [ ] Scope is focused (one responsibility)
+- [ ] SKILL.md body < 500 lines
+- [ ] References are one level deep from SKILL.md
+
+## Output Messages
+
+When creating a skill, inform the user:
+
+```
+✅ Skill created successfully!
+
+📁 Location: .agent/skills/[name]/SKILL.md
+🎯 Purpose: [brief description]
+🔧 How to test: [example prompt that should trigger the skill]
+
+💡 Tip: The agent will use this skill automatically when it detects [context].
+```

package/skills/spec-driven-dev/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: spec-driven-dev
+description: Feature planning with 4 phases - Specify requirements, Design architecture, break into granular Tasks, Implement and Validate. Creates atomic tasks that agents can implement without errors. Triggers on "plan feature", "design", "new feature", "implement feature", "create spec".
+---
+
+# Spec-Driven Development
+
+Plan and implement features with precision. Granular tasks. Clear dependencies. Right tools.
+
+```
+┌──────────┐   ┌──────────┐   ┌─────────┐   ┌───────────────────┐
+│ SPECIFY  │ → │  DESIGN  │ → │  TASKS  │ → │ IMPLEMENT+VALIDATE│
+└──────────┘   └──────────┘   └─────────┘   └───────────────────┘
+```
+
+## Phase Selection
+
+| User wants to... | Load reference |
+|------------------|----------------|
+| Define what to build | [specify.md](references/specify.md) |
+| Design architecture | [design.md](references/design.md) |
+| Break into tasks | [tasks.md](references/tasks.md) |
+| Implement a task | [implement.md](references/implement.md) |
+| Verify it works | [validate.md](references/validate.md) |
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `specify [feature]` | Define requirements |
+| `design [feature]` | Design architecture |
+| `tasks [feature]` | Create task breakdown |
+| `implement T1` | Implement task |
+| `validate` | Verify implementation |
+
+## Output
+
+```
+.specs/[feature-slug]/
+├── spec.md
+├── design.md
+└── tasks.md
+```

package/skills/spec-driven-dev/references/design.md

@@ -0,0 +1,140 @@
+# Phase 2: Design
+
+**Goal**: Define HOW to build it. Architecture, components, what to reuse.
+
+## Process
+
+### 1. Review Specification
+Read `.specs/[feature]/spec.md` before designing.
+
+### 2. Define Architecture
+Overview of how components interact. Use mermaid diagrams when helpful.
+
+### 3. Identify Code Reuse
+**CRITICAL**: What existing code can we leverage? This saves tokens and reduces errors.
+
+### 4. Define Components and Interfaces
+Each component: Purpose, Location, Interfaces, Dependencies, What it reuses.
+
+### 5. Define Data Models
+If the feature involves data, define models before implementation.
+
+---
+
+## Template: `.specs/[feature]/design.md`
+
+```markdown
+# [Feature] Design
+
+**Spec**: `.specs/[feature]/spec.md`
+**Status**: Draft | Approved
+
+---
+
+## Architecture Overview
+
+[Brief description of the architecture approach]
+
+```mermaid
+graph TD
+    A[User Action] --> B[Component A]
+    B --> C[Service Layer]
+    C --> D[Data Store]
+    B --> E[Component B]
+```
+
+---
+
+## Code Reuse Analysis
+
+### Existing Components to Leverage
+
+| Component | Location | How to Use |
+|-----------|----------|------------|
+| [Existing Component] | `src/path/to/file` | [Extend/Import/Reference] |
+| [Existing Utility] | `src/utils/file` | [How it helps] |
+| [Existing Pattern] | `src/patterns/file` | [Apply same pattern] |
+
+### Integration Points
+
+| System | Integration Method |
+|--------|-------------------|
+| [Existing API] | [How new feature connects] |
+| [Database] | [How data connects to existing schemas] |
+
+---
+
+## Components
+
+### [Component Name]
+
+- **Purpose**: [What this component does - one sentence]
+- **Location**: `src/path/to/component/`
+- **Interfaces**: 
+  - `methodName(param: Type): ReturnType` - [description]
+  - `methodName(param: Type): ReturnType` - [description]
+- **Dependencies**: [What it needs to function]
+- **Reuses**: [Existing code this builds upon]
+
+### [Component Name]
+
+- **Purpose**: [What this component does]
+- **Location**: `src/path/to/component/`
+- **Interfaces**: 
+  - `methodName(param: Type): ReturnType`
+- **Dependencies**: [Dependencies]
+- **Reuses**: [Existing code]
+
+---
+
+## Data Models (if applicable)
+
+### [Model Name]
+
+```typescript
+interface ModelName {
+  id: string;
+  field1: string;
+  field2: number;
+  createdAt: Date;
+}
+```
+
+**Relationships**: [How this relates to other models]
+
+### [Model Name]
+
+```typescript
+interface AnotherModel {
+  id: string;
+  // ...
+}
+```
+
+---
+
+## Error Handling Strategy
+
+| Error Scenario | Handling | User Impact |
+|---------------|----------|-------------|
+| [Scenario 1] | [How handled] | [What user sees] |
+| [Scenario 2] | [How handled] | [What user sees] |
+
+---
+
+## Tech Decisions (only non-obvious ones)
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| [What we decided] | [What we chose] | [Why - brief] |
+```
+
+---
+
+## Tips
+
+- **Reuse is king** - Every component should reference existing patterns
+- **Interfaces first** - Define contracts before implementation
+- **Keep it visual** - Diagrams save 1000 words
+- **Small components** - If component does 3+ things, split it
+- **Confirm before Tasks** - User approves design before breaking into tasks

package/skills/spec-driven-dev/references/implement.md

@@ -0,0 +1,66 @@
+# Phase 4a: Implement
+
+**Goal**: Execute ONE task at a time. Use the right tools. Mark done.
+
+## Process
+
+### 1. Pick Task
+
+Either user specifies ("implement T3") or you suggest next available.
+
+### 2. Verify Dependencies
+
+Check tasks.md - are all dependencies marked done?
+
+❌ If not: "T3 depends on T2 which isn't done. Should I do T2 first?"
+
+### 3. Use Specified Tools
+
+**MUST** use the MCPs and Skills listed in the task.
+
+### 4. Implement
+
+Follow the "What" and "Where" exactly. Reference "Reuses" for patterns.
+
+### 5. Verify "Done When"
+
+Check all criteria are met before marking done.
+
+### 6. Update Status
+
+Mark task complete in tasks.md.
+
+---
+
+## Execution Template
+
+```markdown
+## Implementing T[X]: [Task Title]
+
+**Reading**: task definition from tasks.md
+**Dependencies**: [All done? ✅ | Blocked by: TY]
+**Using**:
+- MCP: [from task]
+- Skill: [from task]
+- Reusing: [from task]
+
+### Implementation
+
+[Do the work]
+
+### Verification
+
+- [x] Done when criterion 1
+- [x] Done when criterion 2
+
+**Status**: ✅ Complete | ❌ Blocked | ⚠️ Partial
+```
+
+---
+
+## Tips
+
+- **One task at a time** - Focus prevents errors
+- **Tools matter** - Wrong MCP = wrong approach
+- **Reuses save tokens** - Copy patterns, don't reinvent
+- **Check before mark done** - Verify all criteria

package/skills/spec-driven-dev/references/specify.md

@@ -0,0 +1,116 @@
+# Phase 1: Specify
+
+**Goal**: Capture WHAT to build with testable requirements.
+
+## Process
+
+### 1. Clarify Requirements
+
+Ask the user (2-3 questions to start):
+- "What problem are you solving?"
+- "Who is the user and what's their pain?"
+- "What does success look like?"
+
+If needed:
+- "What are the constraints (time, tech, resources)?"
+- "What is explicitly out of scope?"
+
+### 2. Capture User Stories with Priorities
+
+**P1 = MVP** (must ship), **P2** (should have), **P3** (nice to have)
+
+Each story MUST be **independently testable** - you can implement and demo just that story.
+
+### 3. Write Acceptance Criteria
+
+Use **WHEN/THEN/SHALL** format - it's precise and testable:
+- WHEN [event/action] THEN [system] SHALL [response/behavior]
+
+---
+
+## Template: `.specs/[feature]/spec.md`
+
+```markdown
+# [Feature Name] Specification
+
+## Problem Statement
+
+[Describe the problem in 2-3 sentences. What pain point are we solving? Why now?]
+
+## Goals
+
+- [ ] [Primary goal with measurable outcome]
+- [ ] [Secondary goal with measurable outcome]
+
+## Out of Scope
+
+- [Explicitly NOT building: X]
+- [Explicitly NOT building: Y]
+
+---
+
+## User Stories
+
+### P1: [Story Title] ⭐ MVP
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P1**: [Why this is critical for MVP]
+
+**Acceptance Criteria**:
+1. WHEN [user action/event] THEN system SHALL [expected behavior]
+2. WHEN [user action/event] THEN system SHALL [expected behavior]
+3. WHEN [edge case] THEN system SHALL [graceful handling]
+
+**Independent Test**: [How to verify this story works alone - e.g., "Can demo by doing X and seeing Y"]
+
+---
+
+### P2: [Story Title]
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P2**: [Why this isn't MVP but important]
+
+**Acceptance Criteria**:
+1. WHEN [event] THEN system SHALL [behavior]
+2. WHEN [event] THEN system SHALL [behavior]
+
+**Independent Test**: [How to verify]
+
+---
+
+### P3: [Story Title]
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P3**: [Why this is nice-to-have]
+
+**Acceptance Criteria**:
+1. WHEN [event] THEN system SHALL [behavior]
+
+---
+
+## Edge Cases
+
+- WHEN [boundary condition] THEN system SHALL [behavior]
+- WHEN [error scenario] THEN system SHALL [graceful handling]
+- WHEN [unexpected input] THEN system SHALL [validation response]
+
+---
+
+## Success Criteria
+
+How we know the feature is successful:
+- [ ] [Measurable outcome - e.g., "User can complete X in < 2 minutes"]
+- [ ] [Measurable outcome - e.g., "Zero errors in Y scenario"]
+```
+
+---
+
+## Tips
+
+- **P1 = Vertical Slice** - A complete, demo-able feature, not just backend or frontend
+- **WHEN/THEN is code** - If you can't write it as a test, rewrite it
+- **Edge cases matter** - What breaks? What's empty? What's huge?
+- **Confirm before Design** - User must approve spec before moving on