chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,459 @@
|
||||
# Skill Authoring Standard
|
||||
|
||||
The DNA of every skill in this repository. Follow this standard when creating new skills or upgrading existing ones.
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: "When to use this skill. Include trigger keywords and phrases users might say. Mention related skills for disambiguation."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: domain-name
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
You are an expert in [domain]. Your goal is [specific outcome for the user].
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `[domain]-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Current State
|
||||
- What exists today?
|
||||
- What's working / not working?
|
||||
|
||||
### 2. Goals
|
||||
- What outcome do they want?
|
||||
- What constraints exist?
|
||||
|
||||
### 3. [Domain-Specific Context]
|
||||
- [Questions specific to this skill]
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
This skill supports [N] modes:
|
||||
|
||||
### Mode 1: Build from Scratch
|
||||
When starting fresh — no existing [artifact] to work with.
|
||||
|
||||
### Mode 2: Optimize Existing
|
||||
When improving something that already exists. Analyze what's working, identify gaps, recommend changes.
|
||||
|
||||
### Mode 3: [Situation-Specific]
|
||||
When [specific scenario that needs a different approach].
|
||||
|
||||
## [Core Content Sections]
|
||||
|
||||
[Action-oriented workflow. Not a textbook — a practitioner guiding you through it.]
|
||||
|
||||
[Tables for structured information. Checklists for processes. Examples for clarity.]
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these issues WITHOUT being asked when you notice them in context:
|
||||
|
||||
- [Trigger 1: specific condition → what to flag]
|
||||
- [Trigger 2: specific condition → what to flag]
|
||||
- [Trigger 3: specific condition → what to flag]
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| [Common request 1] | [Specific deliverable with format] |
|
||||
| [Common request 2] | [Specific deliverable with format] |
|
||||
| [Common request 3] | [Specific deliverable with format] |
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
- **Bottom line first** — answer before explanation
|
||||
- **What + Why + How** — every finding has all three
|
||||
- **Actions have owners and deadlines** — no "we should consider"
|
||||
- **Confidence tagging** — 🟢 verified / 🟡 medium / 🔴 assumed
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **skill-name**: Use when [specific scenario]. NOT for [disambiguation].
|
||||
- **skill-name**: Use when [specific scenario]. NOT for [disambiguation].
|
||||
- **skill-name**: Use when [specific scenario]. NOT for [disambiguation].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The 10 Patterns
|
||||
|
||||
### Pattern 1: Context-First
|
||||
|
||||
Every skill checks for domain context before asking questions. Only ask for what's missing.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it before asking questions.
|
||||
Use that context and only ask for information not already covered.
|
||||
```
|
||||
|
||||
**Domain context files:**
|
||||
|
||||
| Domain | Context File | Created By |
|
||||
|--------|-------------|-----------|
|
||||
| C-Suite | `company-context.md` | `/cs:setup` (cs-onboard skill) |
|
||||
| Marketing | `marketing-context.md` | marketing-context skill |
|
||||
| Engineering | `project-context.md` | codebase-onboarding skill |
|
||||
| Product | `product-context.md` | product-strategist skill |
|
||||
| RA/QM | `regulatory-context.md` | regulatory-affairs-head skill |
|
||||
|
||||
**Rules:**
|
||||
- If context exists → read it, use it, only ask for gaps
|
||||
- If context doesn't exist → offer to create it (auto-draft from available info)
|
||||
- Never dump all questions at once — conversational, one section at a time
|
||||
- Push for verbatim language — exact customer/user phrases beat polished descriptions
|
||||
|
||||
---
|
||||
|
||||
### Pattern 2: Practitioner Voice
|
||||
|
||||
Every skill opens with an expert persona and clear goal. Not a textbook — a senior practitioner coaching you.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
You are an expert in [domain]. Your goal is [outcome].
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Write as someone who has done this 100 times
|
||||
- Use contractions, direct language
|
||||
- If something sounds like a Wikipedia article, rewrite it
|
||||
- Opinionated > neutral. State what works and what doesn't.
|
||||
- "Do X" beats "You might consider X"
|
||||
- Industry jargon is fine when talking to practitioners — explain when talking to founders
|
||||
|
||||
**Anti-patterns:**
|
||||
- ❌ "This skill provides comprehensive coverage of..."
|
||||
- ❌ "The following section outlines the various approaches to..."
|
||||
- ❌ "It is recommended that one should consider..."
|
||||
- ✅ "You are an expert in SaaS pricing. Your goal is to help design pricing that captures value."
|
||||
- ✅ "Lead with their world, not yours."
|
||||
- ✅ "If it sounds like marketing copy, rewrite it."
|
||||
|
||||
---
|
||||
|
||||
### Pattern 3: Multi-Mode Workflows
|
||||
|
||||
Most skills have 2-3 natural entry points. Design for all of them.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## How This Skill Works
|
||||
|
||||
### Mode 1: Build from Scratch
|
||||
When starting fresh — [describe the greenfield scenario].
|
||||
|
||||
### Mode 2: Optimize Existing
|
||||
When [artifact] exists but isn't performing. Analyze → identify gaps → recommend.
|
||||
|
||||
### Mode 3: [Situation-Specific]
|
||||
When [edge case or specific scenario that needs a different approach].
|
||||
```
|
||||
|
||||
**Common mode pairs:**
|
||||
|
||||
| Skill Type | Mode 1 | Mode 2 | Mode 3 |
|
||||
|-----------|--------|--------|--------|
|
||||
| CRO skills | Audit a page | Redesign flow | A/B test specific element |
|
||||
| Content skills | Write new | Rewrite/optimize | Repurpose for channel |
|
||||
| SEO skills | Full audit | Fix specific issue | Competitive gap analysis |
|
||||
| Strategy skills | Create plan | Review/critique plan | Pivot existing plan |
|
||||
| Analytics skills | Set up tracking | Debug tracking | Analyze data |
|
||||
|
||||
**Rules:**
|
||||
- Mode 2 (optimize) should ask for current performance data
|
||||
- If user has performance data → use it to inform recommendations
|
||||
- Each mode should be self-contained (don't assume they read the other modes)
|
||||
|
||||
---
|
||||
|
||||
### Pattern 4: Related Skills Navigation
|
||||
|
||||
Every skill ends with a curated list of related skills. Not just links — **when to use each and when NOT to.**
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Related Skills
|
||||
|
||||
- **copywriting**: For landing page and web copy. NOT for email sequences or ad copy.
|
||||
- **page-cro**: For optimizing any marketing page. NOT for signup flows (use signup-flow-cro).
|
||||
- **email-sequence**: For lifecycle/nurture emails. NOT for cold outreach (use cold-email).
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Include 3-7 related skills (not all of them — curate)
|
||||
- Each entry: skill name + WHEN to use + WHEN NOT TO (disambiguation)
|
||||
- Cross-references must be bidirectional (A mentions B, B mentions A)
|
||||
- Include cross-domain references when relevant (e.g., marketing skill → business-growth skill)
|
||||
- Group by relationship type if >5: "Works with", "Instead of", "After this"
|
||||
|
||||
---
|
||||
|
||||
### Pattern 5: Reference Separation
|
||||
|
||||
SKILL.md is the workflow. Reference docs are the knowledge base. Keep them separate.
|
||||
|
||||
**Implementation:**
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # ≤10KB — what to do, how to decide, when to act
|
||||
├── references/
|
||||
│ ├── frameworks.md # Deep framework catalog
|
||||
│ ├── benchmarks.md # Industry data and benchmarks
|
||||
│ ├── platform-specs.md # Platform-specific details
|
||||
│ └── examples.md # Real-world examples
|
||||
├── templates/
|
||||
│ └── template.md # User-fillable templates
|
||||
└── scripts/
|
||||
└── tool.py # Python automation
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- SKILL.md ≤10KB — if it's longer, move content to references
|
||||
- SKILL.md links to references inline: `See [references/frameworks.md](references/frameworks.md) for the full catalog.`
|
||||
- References are loaded on demand — zero startup cost
|
||||
- Each reference doc is self-contained (can be read independently)
|
||||
- Templates are user-fillable files with clear placeholder markers
|
||||
|
||||
---
|
||||
|
||||
### Pattern 6: Proactive Triggers
|
||||
|
||||
Skills surface issues without being asked when they detect patterns in context.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these without being asked:
|
||||
|
||||
- **[Condition]** → [What to flag and why]
|
||||
- **[Condition]** → [What to flag and why]
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- 4-6 triggers per skill
|
||||
- Each trigger: specific condition + business consequence
|
||||
- Triggers should be things the user wouldn't think to ask about
|
||||
- Format: condition → flag → recommended action
|
||||
- Don't trigger on obvious things — trigger on hidden risks
|
||||
|
||||
**Examples:**
|
||||
- SEO: "Keyword cannibalization detected — two pages targeting the same term" → flag
|
||||
- Pricing: "Conversion rate >40% — likely underpriced" → flag
|
||||
- Content: "No content updated in 6+ months" → flag
|
||||
- CRO: "Form has >7 fields with no multi-step" → flag
|
||||
|
||||
---
|
||||
|
||||
### Pattern 7: Output Artifacts
|
||||
|
||||
Map common requests to specific, concrete deliverables.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| "Help with pricing" | Pricing recommendation with tier structure, value metrics, and competitive positioning |
|
||||
| "Audit my SEO" | SEO scorecard (0-100) with prioritized fixes and quick wins |
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- 4-6 artifacts per skill
|
||||
- Each artifact has a specific format (scorecard, matrix, plan, audit, template)
|
||||
- Artifacts are actionable — not just analysis, but recommendations with next steps
|
||||
- Include what the output looks like (table? checklist? narrative?)
|
||||
|
||||
---
|
||||
|
||||
### Pattern 8: Quality Loop
|
||||
|
||||
Skills self-verify before presenting findings.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Communication
|
||||
|
||||
All output passes quality verification:
|
||||
- Self-verify: source attribution, assumption audit, confidence scoring
|
||||
- Peer-verify: cross-functional claims validated by the owning skill
|
||||
- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
|
||||
- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Every finding tagged with confidence level
|
||||
- Assumptions explicitly marked as assumptions
|
||||
- "I don't know" > fake confidence
|
||||
- Cross-functional claims reference the relevant skill
|
||||
- High-stakes recommendations get extra scrutiny
|
||||
|
||||
---
|
||||
|
||||
### Pattern 9: Communication Standard
|
||||
|
||||
Structured output format for all skill output.
|
||||
|
||||
**Standard output:**
|
||||
```
|
||||
BOTTOM LINE: [One sentence answer]
|
||||
|
||||
WHAT:
|
||||
• [Finding 1] — 🟢/🟡/🔴
|
||||
• [Finding 2] — 🟢/🟡/🔴
|
||||
|
||||
WHY THIS MATTERS: [Business impact]
|
||||
|
||||
HOW TO ACT:
|
||||
1. [Action] → [Owner] → [Deadline]
|
||||
|
||||
YOUR DECISION (if needed):
|
||||
Option A: [Description] — [Trade-off]
|
||||
Option B: [Description] — [Trade-off]
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Bottom line first — always
|
||||
- Max 5 bullets per section
|
||||
- Actions have owners and deadlines
|
||||
- Decisions framed as options with trade-offs
|
||||
- No process narration ("First I analyzed...") — results only
|
||||
|
||||
---
|
||||
|
||||
### Pattern 10: Python Tools
|
||||
|
||||
Stdlib-only automation that provides quantitative analysis.
|
||||
|
||||
**Implementation:**
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""Tool description — what it does in one line."""
|
||||
|
||||
import json
|
||||
import sys
|
||||
from collections import Counter
|
||||
|
||||
def main():
|
||||
# Accept input from file arg or stdin
|
||||
# Process with stdlib only
|
||||
# Output JSON for programmatic use
|
||||
# Also print human-readable summary
|
||||
pass
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- **stdlib-only** — zero external dependencies (no pip install)
|
||||
- **CLI-first** — run from command line with file args or stdin
|
||||
- **JSON output** — structured output for integration
|
||||
- **Sample data embedded** — runs with zero config for demo/testing
|
||||
- **One tool, one job** — focused, not Swiss Army knife
|
||||
- **Scoring tools output 0-100** — consistent scale across all tools
|
||||
|
||||
**Naming convention:** `snake_case_verb_noun.py` (e.g., `seo_checker.py`, `headline_scorer.py`, `churn_risk_scorer.py`)
|
||||
|
||||
---
|
||||
|
||||
## File Structure Standard
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # ≤10KB — workflow, decisions, actions
|
||||
├── references/ # Deep knowledge (loaded on demand)
|
||||
│ ├── [topic]-guide.md # Comprehensive guide
|
||||
│ ├── [topic]-benchmarks.md # Industry data
|
||||
│ └── [topic]-examples.md # Real-world examples
|
||||
├── templates/ # User-fillable templates
|
||||
│ └── [artifact]-template.md # With placeholder markers
|
||||
└── scripts/ # Python automation
|
||||
└── [verb]_[noun].py # Stdlib-only, CLI-first
|
||||
```
|
||||
|
||||
**Naming rules:**
|
||||
- Skill folder: `kebab-case`
|
||||
- Python scripts: `snake_case.py`
|
||||
- Reference docs: `kebab-case.md`
|
||||
- Templates: `kebab-case-template.md`
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before a skill is considered done:
|
||||
|
||||
### Structure
|
||||
- [ ] YAML frontmatter with name, description (trigger keywords), version
|
||||
- [ ] Practitioner voice — "You are an expert in X. Your goal is Y."
|
||||
- [ ] Context-first — checks domain context before asking questions
|
||||
- [ ] Multi-mode — at least 2 workflows (build/optimize)
|
||||
- [ ] SKILL.md ≤10KB — heavy content in references/
|
||||
|
||||
### Content
|
||||
- [ ] Action-oriented — tells you what to do, not just what exists
|
||||
- [ ] Opinionated — states what works, not just options
|
||||
- [ ] Tables for structured comparisons
|
||||
- [ ] Checklists for processes
|
||||
- [ ] Examples for clarity
|
||||
|
||||
### Integration
|
||||
- [ ] Related Skills section with WHEN/NOT disambiguation
|
||||
- [ ] Cross-references are bidirectional
|
||||
- [ ] Listed in domain CLAUDE.md
|
||||
- [ ] Listed in `.codex/skills-index.json`
|
||||
- [ ] Listed in `.claude-plugin/marketplace.json`
|
||||
- [ ] Listed in `.gemini/skills-index.json` (run `./scripts/gemini-install.sh`)
|
||||
|
||||
### Quality Standard
|
||||
- [ ] Proactive Triggers (4-6 per skill)
|
||||
- [ ] Output Artifacts table (4-6 per skill)
|
||||
- [ ] Communication standard reference
|
||||
- [ ] Confidence tagging on findings
|
||||
|
||||
### Automation (if applicable)
|
||||
- [ ] Python tool(s) — stdlib-only, CLI-first, JSON output
|
||||
- [ ] Sample data embedded — runs with zero config
|
||||
- [ ] Scoring uses 0-100 scale
|
||||
|
||||
---
|
||||
|
||||
## Domain Context Files
|
||||
|
||||
| Domain | File | Sections |
|
||||
|--------|------|----------|
|
||||
| **C-Suite** | `company-context.md` | Stage, team, burn rate, competitive landscape, strategic priorities |
|
||||
| **Marketing** | `marketing-context.md` | Brand voice, style guide, target keywords, internal links map, competitor analysis, audience personas, writing examples, customer language |
|
||||
| **Engineering** | `project-context.md` | Tech stack, architecture, conventions, CI/CD, testing strategy |
|
||||
| **Product** | `product-context.md` | Roadmap, personas, metrics, feature priorities, user research |
|
||||
| **RA/QM** | `regulatory-context.md` | Device classification, applicable standards, audit schedule, SOUP list |
|
||||
|
||||
Each domain's context skill creates this file via guided interview + auto-draft from available information.
|
||||
|
||||
---
|
||||
|
||||
*This standard applies to all new skills and skill upgrades across the entire repository.*
|
||||
*Version: 1.0.0 | Created: 2026-03-06*
|
||||
Reference in New Issue
Block a user