mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-21 14:58:05 +00:00
feat: Comprehensive documentation update and claude-skills module enhancement
This commit is contained in:
tukuaiai
@@ -0,0 +1,41 @@
|
||||
# skills/claude-skills
|
||||
|
||||
This directory is a **meta-skill**: it turns arbitrary domain material (docs/APIs/code/specs) into a reusable Skill (`SKILL.md` + `references/` + `scripts/` + `assets/`), and ships an executable quality gate + scaffolding.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
claude-skills/
|
||||
|-- AGENTS.md
|
||||
|-- SKILL.md
|
||||
|-- assets/
|
||||
| |-- template-minimal.md
|
||||
| `-- template-complete.md
|
||||
|-- scripts/
|
||||
| |-- create-skill.sh
|
||||
| `-- validate-skill.sh
|
||||
`-- references/
|
||||
|-- index.md
|
||||
|-- README.md
|
||||
|-- anti-patterns.md
|
||||
|-- quality-checklist.md
|
||||
`-- skill-spec.md
|
||||
```
|
||||
|
||||
## File Responsibilities
|
||||
|
||||
- `skills/claude-skills/SKILL.md`: entrypoint (triggers, deliverables, workflow, quality gate, tooling).
|
||||
- `skills/claude-skills/assets/template-minimal.md`: minimal template (small domains / quick bootstrap).
|
||||
- `skills/claude-skills/assets/template-complete.md`: full template (production-grade / complex domains).
|
||||
- `skills/claude-skills/scripts/create-skill.sh`: scaffold generator (minimal/full, output dir, overwrite).
|
||||
- `skills/claude-skills/scripts/validate-skill.sh`: spec validator (supports `--strict`).
|
||||
- `skills/claude-skills/references/index.md`: navigation for this meta-skill's reference docs.
|
||||
- `skills/claude-skills/references/README.md`: upstream official reference (lightly adjusted to keep links working in this repo).
|
||||
- `skills/claude-skills/references/skill-spec.md`: the local Skill spec (MUST/SHOULD/NEVER).
|
||||
- `skills/claude-skills/references/quality-checklist.md`: quality gate checklist + scoring.
|
||||
- `skills/claude-skills/references/anti-patterns.md`: common failure modes and how to fix them.
|
||||
|
||||
## Dependencies & Boundaries
|
||||
|
||||
- `scripts/*.sh`: depend only on `bash` + common POSIX tooling (`sed/awk/grep/find`), no network required.
|
||||
- This directory is about "how to build Skills", not about any specific domain; domain knowledge belongs in `skills/<domain>/`.
|
||||
+169
-342
@@ -1,416 +1,243 @@
|
||||
---
|
||||
name: claude-skills
|
||||
description: Meta-skill for creating, optimizing, and managing Claude Skills. Use when building new skills from documentation, converting domain expertise into AI capabilities, structuring skill files, or learning skill development best practices. This is the foundational skill that generates other skills.
|
||||
description: "Claude Skills meta-skill: extract domain material (docs/APIs/code/specs) into a reusable Skill (SKILL.md + references/scripts/assets), and refactor existing Skills for clarity, activation reliability, and quality gates."
|
||||
---
|
||||
|
||||
# Claude Skills Meta-Skill
|
||||
|
||||
The definitive guide to creating production-grade Claude Skills. This meta-skill teaches Claude how to transform any domain knowledge into structured, reusable AI capabilities.
|
||||
Turn scattered domain material into a Skill that is reusable, maintainable, and reliably activatable:
|
||||
- `SKILL.md` as the entrypoint (triggers, constraints, patterns, examples)
|
||||
- `references/` for long-form evidence and navigation
|
||||
- optional `scripts/` and `assets/` for scaffolding and templates
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
This skill should be triggered when:
|
||||
- Creating a new Claude Skill from scratch
|
||||
- Converting documentation, APIs, or domain knowledge into a Skill
|
||||
- Optimizing or restructuring existing Skills
|
||||
- Learning Skill architecture patterns and best practices
|
||||
- Debugging or troubleshooting Skill behavior
|
||||
- Understanding YAML frontmatter and Skill metadata
|
||||
- Building multi-file Skills with references, scripts, and assets
|
||||
Trigger this meta-skill when you need to:
|
||||
- Create a new Skill from scratch from docs/specs/repos
|
||||
- Refactor an existing Skill (too long, unclear, inconsistent, misfires)
|
||||
- Design reliable activation (frontmatter + triggers + boundaries)
|
||||
- Extract a clean Quick Reference from large material
|
||||
- Split long content into navigable `references/`
|
||||
- Add a quality gate and a validator
|
||||
|
||||
## Not For / Boundaries
|
||||
|
||||
This meta-skill is NOT:
|
||||
- A domain Skill by itself (it builds domain Skills)
|
||||
- A license to invent external facts (if the material does not prove it, say so and add a verification path)
|
||||
- A substitute for required inputs (if inputs are missing, ask 1-3 questions before proceeding)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Skill Directory Structure
|
||||
### Deliverables (What You Must Produce)
|
||||
|
||||
Your output MUST include:
|
||||
1. A concrete directory layout (typically `skills/<skill-name>/`)
|
||||
2. An actionable `SKILL.md` with decidable triggers, boundaries, and reproducible examples
|
||||
3. Long-form docs moved to `references/` with a `references/index.md`
|
||||
4. A pre-delivery checklist (Quality Gate)
|
||||
|
||||
### Recommended Layout (Minimal -> Full)
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Required: Main instructions with YAML frontmatter
|
||||
├── references/ # Optional: Detailed documentation files
|
||||
│ ├── index.md # Navigation index for references
|
||||
│ ├── api.md # API documentation
|
||||
│ └── examples.md # Code examples
|
||||
├── scripts/ # Optional: Helper scripts and automation
|
||||
│ └── setup.sh # Setup/installation scripts
|
||||
└── assets/ # Optional: Templates, configs, media
|
||||
└── templates/ # Boilerplate files
|
||||
|-- SKILL.md # Required: entrypoint with YAML frontmatter
|
||||
|-- references/ # Optional: long-form docs/evidence/index
|
||||
| `-- index.md # Recommended: navigation index
|
||||
|-- scripts/ # Optional: helpers/automation
|
||||
`-- assets/ # Optional: templates/configs/static assets
|
||||
```
|
||||
|
||||
### YAML Frontmatter Specification
|
||||
The truly minimal version is just `SKILL.md` (you can add `references/` later).
|
||||
|
||||
### YAML Frontmatter (Required)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name # Required: lowercase, hyphens, unique
|
||||
description: Complete description # Required: What it does + when to trigger
|
||||
name: skill-name
|
||||
description: "What it does + when to use (activation triggers)."
|
||||
---
|
||||
```
|
||||
|
||||
### Production SKILL.md Template
|
||||
Frontmatter rules:
|
||||
- `name` MUST match `^[a-z][a-z0-9-]*$` and SHOULD match the directory name
|
||||
- `description` MUST be decidable (not "helps with X") and include concrete trigger keywords
|
||||
|
||||
### Minimal `SKILL.md` Skeleton (Copy/Paste)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: [Purpose] + [Trigger conditions]. Use when [specific scenarios].
|
||||
description: "[Domain] capability: includes [capability 1], [capability 2]. Use when [decidable triggers]."
|
||||
---
|
||||
|
||||
# [Skill Name] Skill
|
||||
# my-skill Skill
|
||||
|
||||
[One-paragraph overview]
|
||||
One sentence that states the boundary and the deliverable.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
This skill should be triggered when:
|
||||
- [Trigger 1]
|
||||
Trigger when any of these applies:
|
||||
- [Trigger 1: concrete task/keyword]
|
||||
- [Trigger 2]
|
||||
- [Trigger 3]
|
||||
|
||||
## Not For / Boundaries
|
||||
|
||||
- What this skill will not do (prevents misfires and over-promising)
|
||||
- Required inputs; ask 1-3 questions if missing
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**Pattern 1:** [Name]
|
||||
```[language]
|
||||
[code]
|
||||
**Pattern 1:** one-line explanation
|
||||
```text
|
||||
[command/snippet you can paste and run]
|
||||
```
|
||||
|
||||
### Example Code Patterns
|
||||
## Examples
|
||||
|
||||
**Example 1** ([language]):
|
||||
```[language]
|
||||
[complete working example]
|
||||
### Example 1
|
||||
- Input:
|
||||
- Steps:
|
||||
- Expected output / acceptance:
|
||||
|
||||
### Example 2
|
||||
|
||||
### Example 3
|
||||
|
||||
## References
|
||||
|
||||
- `references/index.md`: navigation
|
||||
- `references/...`: long-form docs split by topic
|
||||
|
||||
## Maintenance
|
||||
|
||||
- Sources: docs/repos/specs (do not invent)
|
||||
- Last updated: YYYY-MM-DD
|
||||
- Known limits: what is explicitly out of scope
|
||||
```
|
||||
|
||||
## Reference Files
|
||||
### Authoring Rules (Non-negotiable)
|
||||
|
||||
This skill includes documentation in `references/`:
|
||||
- **[file.md]** - [Description]
|
||||
1. Quick Reference is for short, directly usable patterns
|
||||
- Keep it <= 20 patterns when possible.
|
||||
- Anything that needs paragraphs of explanation goes to `references/`.
|
||||
2. Activation must be decidable
|
||||
- Frontmatter `description` should say "what + when" with concrete keywords.
|
||||
- "When to Use" must list specific tasks/inputs/goals, not vague help text.
|
||||
- "Not For / Boundaries" is mandatory for reliability.
|
||||
3. No bluffing on external details
|
||||
- If the material does not prove it, say so and include a verification path.
|
||||
|
||||
## Working with This Skill
|
||||
### Workflow (Material -> Skill)
|
||||
|
||||
### For Beginners
|
||||
[Getting started guidance]
|
||||
Do not skip steps:
|
||||
1. Scope: write MUST/SHOULD/NEVER (three sentences total is fine)
|
||||
2. Extract patterns: pick 10-20 high-frequency patterns (commands/snippets/flows)
|
||||
3. Add examples: >= 3 end-to-end examples (input -> steps -> acceptance)
|
||||
4. Define boundaries: what is out-of-scope + required inputs
|
||||
5. Split references: move long text into `references/` + write `references/index.md`
|
||||
6. Apply the gate: run the checklist and the validator
|
||||
|
||||
### For Specific Features
|
||||
[How to find detailed information]
|
||||
### Quality Gate (Pre-delivery Checklist)
|
||||
|
||||
## Resources
|
||||
Minimum checks (see `references/quality-checklist.md` for the full version):
|
||||
1. `name` matches `^[a-z][a-z0-9-]*$` and matches the directory name
|
||||
2. `description` states "what + when" with concrete trigger keywords
|
||||
3. Has "When to Use This Skill" with decidable triggers
|
||||
4. Has "Not For / Boundaries" to reduce misfires
|
||||
5. Quick Reference is <= 20 patterns and each is directly usable
|
||||
6. Has >= 3 reproducible examples
|
||||
7. Long content is in `references/` and `references/index.md` is navigable
|
||||
8. Uncertain claims include a verification path (no bluffing)
|
||||
9. Reads like an operator's manual, not a documentation dump
|
||||
|
||||
### references/
|
||||
[Description]
|
||||
|
||||
### scripts/
|
||||
[Description]
|
||||
|
||||
### assets/
|
||||
[Description]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### What is a Skill?
|
||||
|
||||
**A Skill is a folder containing instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.**
|
||||
|
||||
Skills teach Claude to:
|
||||
- Apply domain-specific knowledge consistently
|
||||
- Follow organization-specific workflows
|
||||
- Work with specific APIs, file formats, or tools
|
||||
- Automate complex multi-step processes
|
||||
|
||||
### Skill Activation Triggers
|
||||
|
||||
Skills activate based on:
|
||||
- **Explicit mention**: "Use the [skill-name] skill to..."
|
||||
- **Description matching**: Task matches skill's description keywords
|
||||
- **Context relevance**: Task domain aligns with skill's purpose
|
||||
|
||||
---
|
||||
|
||||
## Creating Production-Grade Skills
|
||||
|
||||
### Step 1: Define Scope
|
||||
|
||||
Answer before writing:
|
||||
1. What specific problem does this skill solve?
|
||||
2. What triggers should activate this skill?
|
||||
3. What are the boundaries (what it should NOT do)?
|
||||
|
||||
### Step 2: Gather Source Material
|
||||
|
||||
Collect:
|
||||
- Official documentation
|
||||
- API references
|
||||
- Code examples and patterns
|
||||
- Common errors and solutions
|
||||
|
||||
### Step 3: Structure the SKILL.md
|
||||
|
||||
**Critical sections:**
|
||||
1. YAML frontmatter with comprehensive description
|
||||
2. "When to Use This Skill" with specific triggers
|
||||
3. "Quick Reference" with common patterns
|
||||
4. Code examples that are complete and working
|
||||
5. Reference file pointers
|
||||
|
||||
### Step 4: Create Reference Files
|
||||
|
||||
**references/index.md:**
|
||||
```markdown
|
||||
# [Skill Name] Documentation Index
|
||||
|
||||
## Quick Links
|
||||
- Getting Started → `getting_started.md`
|
||||
- API Reference → `api.md`
|
||||
- Examples → `examples.md`
|
||||
```
|
||||
|
||||
### Step 5: Add Scripts and Assets
|
||||
Validate locally:
|
||||
|
||||
```bash
|
||||
# scripts/setup.sh
|
||||
#!/bin/bash
|
||||
echo "Setting up [skill-name]..."
|
||||
# From repo root (basic validation)
|
||||
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name>
|
||||
|
||||
# From repo root (strict validation)
|
||||
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name> --strict
|
||||
|
||||
# From skills/claude-skills/ (basic validation)
|
||||
./scripts/validate-skill.sh ../<skill-name>
|
||||
|
||||
# From skills/claude-skills/ (strict validation)
|
||||
./scripts/validate-skill.sh ../<skill-name> --strict
|
||||
```
|
||||
|
||||
---
|
||||
### Tools & Templates
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Description Writing
|
||||
|
||||
```yaml
|
||||
# ❌ Too vague
|
||||
description: Helps with databases
|
||||
|
||||
# ✅ Comprehensive
|
||||
description: PostgreSQL database development including SQL queries, schema design, performance optimization. Use when working with PostgreSQL, writing SQL, or managing databases.
|
||||
```
|
||||
|
||||
### Trigger Conditions
|
||||
|
||||
```markdown
|
||||
# ❌ Vague
|
||||
- Working with code
|
||||
|
||||
# ✅ Specific
|
||||
- Writing PostgreSQL queries or stored procedures
|
||||
- Designing database schemas or indexes
|
||||
- Optimizing slow queries
|
||||
```
|
||||
|
||||
### Code Examples
|
||||
|
||||
```markdown
|
||||
# ❌ Incomplete
|
||||
```sql
|
||||
SELECT * FROM users
|
||||
```
|
||||
|
||||
# ✅ Complete with context
|
||||
**Example: Paginated query with filtering**
|
||||
```sql
|
||||
SELECT id, username, email, created_at
|
||||
FROM users
|
||||
WHERE status = 'active'
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 20 OFFSET 0;
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Patterns by Category
|
||||
|
||||
### API/Library Skills
|
||||
|
||||
```markdown
|
||||
## Quick Reference
|
||||
|
||||
### Authentication
|
||||
```python
|
||||
client = APIClient(api_key="your-key")
|
||||
```
|
||||
|
||||
### Common Operations
|
||||
```python
|
||||
# Create
|
||||
resource = client.create(name="example")
|
||||
|
||||
# List
|
||||
resources = client.list(limit=10)
|
||||
|
||||
# Delete
|
||||
client.delete(resource_id)
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
```python
|
||||
try:
|
||||
result = client.operation()
|
||||
except APIError as e:
|
||||
print(f"Error {e.code}: {e.message}")
|
||||
```
|
||||
```
|
||||
|
||||
### Framework Skills
|
||||
|
||||
```markdown
|
||||
## Project Structure
|
||||
```
|
||||
my-project/
|
||||
├── src/
|
||||
├── tests/
|
||||
└── config/
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
```bash
|
||||
framework init my-project
|
||||
framework dev
|
||||
framework build
|
||||
```
|
||||
```
|
||||
|
||||
### Domain Knowledge Skills
|
||||
|
||||
```markdown
|
||||
## Core Concepts
|
||||
|
||||
### Concept 1
|
||||
[Explanation]
|
||||
|
||||
### Concept 2
|
||||
[Explanation]
|
||||
|
||||
## Decision Framework
|
||||
|
||||
When to use Approach A:
|
||||
- [Condition 1]
|
||||
- [Condition 2]
|
||||
|
||||
When to use Approach B:
|
||||
- [Condition 1]
|
||||
- [Condition 2]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Generating Skills from Source Material
|
||||
|
||||
### Transformation Process
|
||||
|
||||
```
|
||||
Source Material
|
||||
↓
|
||||
Extract: concepts, patterns, examples, edge cases, errors
|
||||
↓
|
||||
Structure: YAML → When to Use → Quick Reference → Details
|
||||
↓
|
||||
Create: references/index.md + categorized docs
|
||||
↓
|
||||
Production-Grade Skill
|
||||
```
|
||||
|
||||
### Generation Prompt
|
||||
|
||||
When creating a skill from source material:
|
||||
|
||||
```
|
||||
Create a production-grade Claude Skill:
|
||||
|
||||
1. Analyze source material
|
||||
2. Extract core concepts and patterns
|
||||
3. Create SKILL.md with:
|
||||
- Comprehensive description (purpose + triggers)
|
||||
- Specific "When to Use" conditions
|
||||
- Quick Reference with code patterns
|
||||
- Complete working examples
|
||||
4. Create references/index.md
|
||||
5. Organize detailed docs in references/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform Integration
|
||||
|
||||
### Claude Code
|
||||
Generate a new Skill skeleton:
|
||||
|
||||
```bash
|
||||
# Add marketplace
|
||||
/plugin marketplace add anthropics/skills
|
||||
# From repo root (generate into ./skills/)
|
||||
./skills/claude-skills/scripts/create-skill.sh my-skill --full --output skills
|
||||
|
||||
# Install
|
||||
/plugin install example-skills@anthropic-agent-skills
|
||||
# From skills/claude-skills/ (generate into ../ i.e. ./skills/)
|
||||
./scripts/create-skill.sh my-skill --full --output ..
|
||||
|
||||
# Use
|
||||
"Use the PDF skill to extract tables from report.pdf"
|
||||
# Minimal skeleton
|
||||
./skills/claude-skills/scripts/create-skill.sh my-skill --minimal --output skills
|
||||
```
|
||||
|
||||
### Claude.ai
|
||||
Templates:
|
||||
- `assets/template-minimal.md`
|
||||
- `assets/template-complete.md`
|
||||
|
||||
1. Navigate to Claude.ai (paid plan)
|
||||
2. Upload custom skill folder
|
||||
3. Reference in conversations
|
||||
## Examples
|
||||
|
||||
### Claude API
|
||||
### Example 1: Create a Skill from Docs
|
||||
|
||||
See: https://docs.claude.com/en/api/skills-guide
|
||||
- Input: an official doc/spec + 2-3 real code samples + common failure modes
|
||||
- Steps:
|
||||
1. Run `create-skill.sh` to scaffold `skills/<skill-name>/`
|
||||
2. Write frontmatter `description` as "what + when"
|
||||
3. Extract 10-20 high-frequency patterns into Quick Reference
|
||||
4. Add >= 3 end-to-end examples with acceptance criteria
|
||||
5. Put long content into `references/` and wire `references/index.md`
|
||||
6. Run `validate-skill.sh --strict` and iterate
|
||||
|
||||
---
|
||||
### Example 2: Refactor a "Doc Dump" Skill
|
||||
|
||||
## Troubleshooting
|
||||
- Input: an existing `SKILL.md` with long pasted documentation
|
||||
- Steps:
|
||||
1. Identify which parts are patterns vs. long-form explanation
|
||||
2. Move long-form text into `references/` (split by topic)
|
||||
3. Rewrite Quick Reference as short copy/paste patterns
|
||||
4. Add or fix Examples until they are reproducible
|
||||
5. Add "Not For / Boundaries" to reduce misfires
|
||||
|
||||
### Skill Not Activating
|
||||
### Example 3: Validate and Gate a Skill
|
||||
|
||||
1. Check `description` includes trigger keywords
|
||||
2. Verify `name` is lowercase with hyphens
|
||||
3. Ensure valid YAML (no tabs)
|
||||
4. Try explicit: "Use the [skill-name] skill to..."
|
||||
- Input: `skills/<skill-name>/`
|
||||
- Steps:
|
||||
1. Run `validate-skill.sh` (non-strict) to get warnings
|
||||
2. Fix frontmatter/name mismatches and missing sections
|
||||
3. Run `validate-skill.sh --strict` to enforce the spec
|
||||
4. Run the scoring rubric in `references/quality-checklist.md` before shipping
|
||||
|
||||
### Inconsistent Behavior
|
||||
## References
|
||||
|
||||
1. Add more specific trigger conditions
|
||||
2. Include more code examples
|
||||
3. Make instructions unambiguous
|
||||
4. Add explicit constraints
|
||||
Local docs:
|
||||
- `references/index.md`
|
||||
- `references/skill-spec.md`
|
||||
- `references/quality-checklist.md`
|
||||
- `references/anti-patterns.md`
|
||||
- `references/README.md` (upstream official reference)
|
||||
|
||||
---
|
||||
External (official):
|
||||
- https://support.claude.com/en/articles/12512176-what-are-skills
|
||||
- https://support.claude.com/en/articles/12512180-using-skills-in-claude
|
||||
- https://support.claude.com/en/articles/12512198-creating-custom-skills
|
||||
- https://docs.claude.com/en/api/skills-guide
|
||||
|
||||
## Reference Files
|
||||
## Maintenance
|
||||
|
||||
This skill includes documentation in `references/`:
|
||||
|
||||
- **README.md** - Official Anthropic Skills repository documentation
|
||||
- **index.md** - Documentation index and quick links
|
||||
|
||||
## Working with This Skill
|
||||
|
||||
### For Creating New Skills
|
||||
Follow the 5-step process in "Creating Production-Grade Skills"
|
||||
|
||||
### For Optimizing Existing Skills
|
||||
Review "Best Practices" and compare against your skill
|
||||
|
||||
### For Understanding Architecture
|
||||
Read "Core Concepts" for foundational understanding
|
||||
|
||||
## Resources
|
||||
|
||||
### references/
|
||||
- Official Anthropic documentation
|
||||
- Navigation index
|
||||
|
||||
### scripts/
|
||||
- `create-skill.sh` - Quick skill directory generator
|
||||
|
||||
### assets/
|
||||
- `template-minimal.md` - Minimal template
|
||||
- `template-complete.md` - Full production template
|
||||
|
||||
## Notes
|
||||
|
||||
- Skills are portable across Claude Code, Claude.ai, and API
|
||||
- The `description` field is critical for reliable activation
|
||||
- Code examples should be complete and immediately usable
|
||||
- This skill generates other production-grade skills
|
||||
- Sources: local spec files in `skills/claude-skills/references/` + upstream official docs in `references/README.md`
|
||||
- Last updated: 2025-12-14
|
||||
- Known limits: `validate-skill.sh` is heuristic; strict mode assumes the recommended section headings
|
||||
|
||||
@@ -1,109 +1,88 @@
|
||||
---
|
||||
name: my-skill
|
||||
description: [Domain] development and operations including [capability 1], [capability 2], [capability 3]. Use when working with [domain], implementing [solutions], or troubleshooting [issues].
|
||||
name: {{skill_name}}
|
||||
description: "[Domain] end-to-end capability: includes [capability 1], [capability 2], [capability 3]. Use when [decidable triggers]."
|
||||
---
|
||||
|
||||
# [Skill Name] Skill
|
||||
# {{skill_name}} Skill
|
||||
|
||||
Comprehensive assistance with [domain] development, generated from official documentation.
|
||||
Production-grade skill for [domain]: extract rules, patterns, and reproducible examples from source material (avoid documentation dumps).
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
This skill should be triggered when:
|
||||
- Working with [domain/technology]
|
||||
- Asking about [domain] features or APIs
|
||||
- Implementing [domain] solutions
|
||||
- Debugging [domain] code
|
||||
- Learning [domain] best practices
|
||||
Trigger when any of these applies:
|
||||
- You are designing/implementing/debugging [domain/tech]
|
||||
- You need to turn requirements into concrete commands/code/configs
|
||||
- You need common pitfalls, boundaries, and acceptance criteria
|
||||
|
||||
## Not For / Boundaries
|
||||
|
||||
- What this skill will not do (prevents misfires and over-promising)
|
||||
- Required inputs; ask 1-3 questions if missing
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**Pattern 1:** [Name]
|
||||
```[language]
|
||||
[code example]
|
||||
**Pattern 1:** one-line explanation
|
||||
```text
|
||||
[command/snippet you can paste and run]
|
||||
```
|
||||
|
||||
**Pattern 2:** [Name]
|
||||
```[language]
|
||||
[code example]
|
||||
**Pattern 2:**
|
||||
```text
|
||||
[command/snippet you can paste and run]
|
||||
```
|
||||
|
||||
**Pattern 3:** [Name]
|
||||
```[language]
|
||||
[code example]
|
||||
```
|
||||
## Rules & Constraints
|
||||
|
||||
### Example Code Patterns
|
||||
- MUST: non-negotiable rules (security boundaries, defaults, acceptance)
|
||||
- SHOULD: strong recommendations (best practices, performance habits)
|
||||
- NEVER: explicit prohibitions (dangerous ops, inventing facts)
|
||||
|
||||
**Example 1** ([language]):
|
||||
```[language]
|
||||
// [Description of what this example demonstrates]
|
||||
[complete working code]
|
||||
```
|
||||
## Examples
|
||||
|
||||
**Example 2** ([language]):
|
||||
```[language]
|
||||
// [Description]
|
||||
[complete working code]
|
||||
```
|
||||
### Example 1
|
||||
- Input:
|
||||
- Steps:
|
||||
- Expected output / acceptance:
|
||||
|
||||
## [Domain-Specific Section 1]
|
||||
### Example 2
|
||||
|
||||
### [Subsection]
|
||||
### Example 3
|
||||
|
||||
[Content]
|
||||
## FAQ
|
||||
|
||||
### [Subsection]
|
||||
- Q: ...
|
||||
- A: ...
|
||||
|
||||
[Content]
|
||||
## Troubleshooting
|
||||
|
||||
## [Domain-Specific Section 2]
|
||||
- Symptom -> Likely causes -> Diagnosis -> Fix
|
||||
|
||||
### [Subsection]
|
||||
## References
|
||||
|
||||
[Content]
|
||||
- `references/index.md`: navigation
|
||||
- `references/getting_started.md`: onboarding and vocabulary
|
||||
- `references/api.md`: API/CLI/config reference (if applicable)
|
||||
- `references/examples.md`: long examples and extra use cases
|
||||
- `references/troubleshooting.md`: edge cases and failure modes
|
||||
|
||||
## Reference Files
|
||||
## Maintenance
|
||||
|
||||
This skill includes comprehensive documentation in `references/`:
|
||||
- Sources: docs/repos/specs (do not invent)
|
||||
- Last updated: YYYY-MM-DD
|
||||
- Known limits: what is explicitly out of scope
|
||||
|
||||
- **getting_started.md** - Installation, setup, first steps
|
||||
- **api.md** - Complete API reference
|
||||
- **examples.md** - Code examples by use case
|
||||
- **troubleshooting.md** - Common issues and solutions
|
||||
## Quality Gate
|
||||
|
||||
Use `view` to read specific reference files when detailed information is needed.
|
||||
Minimum checks before shipping (see meta-skill `claude-skills` for the full version):
|
||||
|
||||
## Working with This Skill
|
||||
|
||||
### For Beginners
|
||||
Start with the getting_started reference file for foundational concepts.
|
||||
|
||||
### For Specific Features
|
||||
Use the api reference file for detailed function/method information.
|
||||
|
||||
### For Code Examples
|
||||
The examples reference file contains patterns organized by use case.
|
||||
|
||||
## Resources
|
||||
|
||||
### references/
|
||||
Organized documentation extracted from official sources:
|
||||
- Detailed explanations
|
||||
- Code examples with language annotations
|
||||
- Links to original documentation
|
||||
|
||||
### scripts/
|
||||
Helper scripts for common automation tasks.
|
||||
|
||||
### assets/
|
||||
Templates, boilerplate, and example configurations.
|
||||
|
||||
## Notes
|
||||
|
||||
- This skill was generated from official documentation
|
||||
- Reference files preserve structure from source docs
|
||||
- Code examples include language detection for syntax highlighting
|
||||
- Quick reference patterns are extracted from common usage
|
||||
1. `description` is decidable ("what + when") and includes trigger keywords
|
||||
2. Has "When to Use This Skill" with decidable triggers
|
||||
3. Has "Not For / Boundaries" to reduce misfires
|
||||
4. Quick Reference is <= 20 patterns and each is directly usable
|
||||
5. Has >= 3 reproducible examples (input -> steps -> acceptance)
|
||||
6. Long content is in `references/` with a navigable `references/index.md`
|
||||
7. Uncertain claims include a verification path (no bluffing)
|
||||
8. No documentation dumps in Quick Reference
|
||||
9. Reads like an operator's manual, not a knowledge dump
|
||||
|
||||
@@ -1,37 +1,50 @@
|
||||
---
|
||||
name: my-skill
|
||||
description: [Domain] assistance including [key capability]. Use when [trigger condition].
|
||||
name: {{skill_name}}
|
||||
description: "[Domain] capability: includes [key capability]. Use when [decidable triggers]."
|
||||
---
|
||||
|
||||
# [Skill Name] Skill
|
||||
# {{skill_name}} Skill
|
||||
|
||||
[One-sentence overview of what this skill does]
|
||||
One sentence that states the boundary and the deliverable.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
This skill should be triggered when:
|
||||
- [Trigger 1]
|
||||
Trigger when any of these applies:
|
||||
- [Trigger 1: concrete task/keyword]
|
||||
- [Trigger 2]
|
||||
- [Trigger 3]
|
||||
|
||||
## Not For / Boundaries
|
||||
|
||||
- What this skill will not do (prevents misfires and over-promising)
|
||||
- Required inputs; ask 1-3 questions if missing
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**Pattern 1:**
|
||||
```[language]
|
||||
[code]
|
||||
**Pattern 1:** one-line explanation
|
||||
```text
|
||||
[command/snippet you can paste and run]
|
||||
```
|
||||
|
||||
**Pattern 2:**
|
||||
```[language]
|
||||
[code]
|
||||
```
|
||||
## Examples
|
||||
|
||||
## Resources
|
||||
### Example 1
|
||||
- Input:
|
||||
- Steps:
|
||||
- Expected output / acceptance:
|
||||
|
||||
### references/
|
||||
[Documentation files if any]
|
||||
### Example 2
|
||||
|
||||
### scripts/
|
||||
[Helper scripts if any]
|
||||
### Example 3
|
||||
|
||||
## References
|
||||
|
||||
- `references/index.md`: navigation
|
||||
- `references/...`: long-form docs split by topic
|
||||
|
||||
## Maintenance
|
||||
|
||||
- Sources: docs/repos/specs (do not invent)
|
||||
- Last updated: YYYY-MM-DD
|
||||
|
||||
@@ -13,7 +13,7 @@ This repository contains example skills that demonstrate what's possible with Cl
|
||||
|
||||
Each skill is self-contained in its own directory with a `SKILL.md` file containing the instructions and metadata that Claude uses. Browse through these examples to get inspiration for your own skills or to understand different patterns and approaches.
|
||||
|
||||
The example skills in this repo are open source (Apache 2.0). We've also included the document creation & editing skills that power [Claude's document capabilities](https://www.anthropic.com/news/create-files) under the hood in the [`document-skills/`](./document-skills/) folder. These are source-available, not open source, but we wanted to share these with developers as a reference for more complex skills that are actively used in a production AI application.
|
||||
The example skills in this repo are open source (Apache 2.0). We've also included the document creation & editing skills that power [Claude's document capabilities](https://www.anthropic.com/news/create-files) under the hood in the [`skills/`](https://github.com/anthropics/skills/tree/main/skills) directory. These are source-available, not open source, but we wanted to share these with developers as a reference for more complex skills that are actively used in a production AI application.
|
||||
|
||||
**Note:** These are reference examples for inspiration and learning. They showcase general-purpose capabilities rather than organization-specific workflows or sensitive content.
|
||||
|
||||
@@ -120,4 +120,4 @@ The markdown content below contains the instructions, examples, and guidelines t
|
||||
|
||||
Skills are a great way to teach Claude how to get better at using specific pieces of software. As we see awesome example skills from partners, we may highlight some of them here:
|
||||
|
||||
- **Notion** - [Notion Skills for Claude](https://www.notion.so/notiondevs/Notion-Skills-for-Claude-28da4445d27180c7af1df7d8615723d0)
|
||||
- **Notion** - [Notion Skills for Claude](https://www.notion.so/notiondevs/Notion-Skills-for-Claude-28da4445d27180c7af1df7d8615723d0)
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
# Anti-Patterns (And How to Fix Them)
|
||||
|
||||
This file documents common ways Skills fail in practice. Use it when refactoring existing Skills.
|
||||
|
||||
## 1) Documentation Dump in Quick Reference
|
||||
|
||||
**Symptom**
|
||||
- Quick Reference contains paragraphs of text, pasted docs, or large excerpts.
|
||||
|
||||
**Why it fails**
|
||||
- Users cannot scan or reuse it.
|
||||
- The model treats it as "knowledge soup" rather than executable patterns.
|
||||
|
||||
**Fix**
|
||||
- Move long text into `references/` (split by topic).
|
||||
- Keep Quick Reference as <= 20 copy/paste patterns when possible.
|
||||
- Add Examples for anything non-trivial.
|
||||
|
||||
## 2) Vague Triggers ("Helps with X")
|
||||
|
||||
**Symptom**
|
||||
- `description` says "helps with databases" or similar.
|
||||
- "When to Use" is a generic list with no tasks/inputs/goals.
|
||||
|
||||
**Why it fails**
|
||||
- Activation becomes noisy and unpredictable.
|
||||
|
||||
**Fix**
|
||||
- Rewrite `description` as: "What + when".
|
||||
- In "When to Use", list decidable tasks:
|
||||
- "Writing migration SQL for PostgreSQL"
|
||||
- "Debugging a failing CCXT order placement"
|
||||
- Add "Not For / Boundaries" to prevent misfires.
|
||||
|
||||
## 3) Missing Boundaries
|
||||
|
||||
**Symptom**
|
||||
- The Skill never says what it will not do.
|
||||
|
||||
**Why it fails**
|
||||
- The model over-promises and makes unsafe assumptions.
|
||||
- The skill triggers in irrelevant contexts.
|
||||
|
||||
**Fix**
|
||||
- Add `## Not For / Boundaries` with:
|
||||
- explicit out-of-scope items
|
||||
- required inputs and what questions to ask when missing
|
||||
|
||||
## 4) Non-reproducible Examples
|
||||
|
||||
**Symptom**
|
||||
- Examples are pseudo-code, missing inputs, or missing expected outputs.
|
||||
|
||||
**Why it fails**
|
||||
- Users cannot trust or validate the behavior.
|
||||
|
||||
**Fix**
|
||||
- Each example should contain:
|
||||
- Input(s)
|
||||
- Steps
|
||||
- Expected output / acceptance criteria
|
||||
- Prefer minimal reproducible examples over big "showcase" code.
|
||||
|
||||
## 5) One Giant File Syndrome
|
||||
|
||||
**Symptom**
|
||||
- Everything is in `SKILL.md` (or one huge reference file).
|
||||
|
||||
**Why it fails**
|
||||
- The entrypoint becomes unscannable and hard to maintain.
|
||||
|
||||
**Fix**
|
||||
- Keep `SKILL.md` execution-focused (patterns + examples + boundaries).
|
||||
- Split long content into `references/` and add `references/index.md`.
|
||||
|
||||
## 6) Invented Facts and Unverifiable Claims
|
||||
|
||||
**Symptom**
|
||||
- The Skill claims API fields/flags/commands without citing sources.
|
||||
|
||||
**Why it fails**
|
||||
- Incorrect guidance is worse than missing guidance.
|
||||
|
||||
**Fix**
|
||||
- Add a "verification path": where/how to confirm in official docs or source code.
|
||||
- Prefer statements backed by your material; mark assumptions explicitly.
|
||||
|
||||
## 7) Unsafe Defaults and Destructive Commands
|
||||
|
||||
**Symptom**
|
||||
- The Skill suggests destructive commands as the default path.
|
||||
|
||||
**Why it fails**
|
||||
- Users copy/paste and lose data.
|
||||
|
||||
**Fix**
|
||||
- Put destructive actions behind explicit warnings and confirmation steps.
|
||||
- Prefer read-only diagnostics first.
|
||||
|
||||
## 8) Inconsistent Terminology
|
||||
|
||||
**Symptom**
|
||||
- Same concept has multiple names; different concepts share a name.
|
||||
|
||||
**Why it fails**
|
||||
- Increases cognitive load and produces inconsistent outputs.
|
||||
|
||||
**Fix**
|
||||
- Add a short glossary (in `references/getting_started.md` or similar).
|
||||
- Use one concept, one name.
|
||||
@@ -1,100 +1,26 @@
|
||||
# Claude Skills Documentation Index
|
||||
# Claude Skills Meta-Skill Reference Index
|
||||
|
||||
## Overview
|
||||
This directory contains long-form documentation that supports the `claude-skills` meta-skill.
|
||||
|
||||
This index provides navigation for the Claude Skills meta-skill documentation.
|
||||
## Start Here
|
||||
|
||||
## Categories
|
||||
- [`../SKILL.md`](../SKILL.md): the meta-skill entrypoint (workflow, quality gate, tooling)
|
||||
|
||||
### Official Documentation
|
||||
**File:** `README.md`
|
||||
## Local Reference Docs (This Repo)
|
||||
|
||||
Complete overview of Claude Skills including:
|
||||
- What are skills and how they work
|
||||
- Example skills by category
|
||||
- Document skills (source-available)
|
||||
- Usage across platforms (Claude Code, Claude.ai, API)
|
||||
- Creating basic skills
|
||||
- [`skill-spec.md`](skill-spec.md): normative spec (MUST/SHOULD/NEVER) for a production-grade Skill in this repo
|
||||
- [`quality-checklist.md`](quality-checklist.md): quality gate checklist + scoring rubric
|
||||
- [`anti-patterns.md`](anti-patterns.md): common failure modes and how to fix them
|
||||
|
||||
## Quick Links
|
||||
## Upstream / Official Reference
|
||||
|
||||
| Topic | File | Section |
|
||||
|-------|------|---------|
|
||||
| What are skills | `README.md` | Lines 1-9 |
|
||||
| Example skills list | `README.md` | Lines 24-45 |
|
||||
| Document skills | `README.md` | Lines 47-56 |
|
||||
| Claude Code setup | `README.md` | Lines 58-78 |
|
||||
| Claude.ai usage | `README.md` | Lines 80-84 |
|
||||
| Claude API | `README.md` | Lines 86-88 |
|
||||
| Creating a skill | `README.md` | Lines 90-117 |
|
||||
- [`README.md`](README.md): upstream overview of Claude Skills (what skills are, usage, examples)
|
||||
|
||||
## Skill Structure Reference
|
||||
## External Links (Official)
|
||||
|
||||
### Required Files
|
||||
|
||||
```
|
||||
skill-name/
|
||||
└── SKILL.md # Main instructions with YAML frontmatter
|
||||
```
|
||||
|
||||
### Optional Directories
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md
|
||||
├── references/ # Documentation files
|
||||
├── scripts/ # Helper scripts
|
||||
└── assets/ # Templates, configs
|
||||
```
|
||||
|
||||
### YAML Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name # lowercase, hyphens
|
||||
description: What + When # Purpose and trigger conditions
|
||||
---
|
||||
```
|
||||
|
||||
## Topics Covered
|
||||
|
||||
### Getting Started
|
||||
- What skills are
|
||||
- How skills work
|
||||
- Platform availability
|
||||
- Installation methods
|
||||
|
||||
### Skill Categories
|
||||
|
||||
| Category | Examples |
|
||||
|----------|----------|
|
||||
| Creative | algorithmic-art, canvas-design, slack-gif-creator |
|
||||
| Development | artifacts-builder, mcp-server, webapp-testing |
|
||||
| Enterprise | brand-guidelines, internal-comms, theme-factory |
|
||||
| Documents | docx, pdf, pptx, xlsx |
|
||||
| Meta | skill-creator, template-skill |
|
||||
|
||||
### Platform Integration
|
||||
|
||||
| Platform | Method |
|
||||
|----------|--------|
|
||||
| Claude Code | `/plugin marketplace add anthropics/skills` |
|
||||
| Claude.ai | Upload via skills interface |
|
||||
| Claude API | Skills API endpoint |
|
||||
|
||||
## External Resources
|
||||
|
||||
### Official Links
|
||||
- [What are skills?](https://support.claude.com/en/articles/12512176-what-are-skills)
|
||||
- [Using skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
|
||||
- [Creating custom skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
|
||||
- [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide)
|
||||
- [Anthropic Skills GitHub](https://github.com/anthropics/skills)
|
||||
|
||||
### Blog Posts
|
||||
- [Equipping agents with Agent Skills](https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
|
||||
|
||||
## License
|
||||
|
||||
- Example skills: Apache 2.0 (open source)
|
||||
- Document skills: Source-available (reference only)
|
||||
- What are skills? https://support.claude.com/en/articles/12512176-what-are-skills
|
||||
- Using skills in Claude https://support.claude.com/en/articles/12512180-using-skills-in-claude
|
||||
- Creating custom skills https://support.claude.com/en/articles/12512198-creating-custom-skills
|
||||
- Skills API Quickstart https://docs.claude.com/en/api/skills-guide
|
||||
- Anthropic Skills GitHub https://github.com/anthropics/skills
|
||||
- Engineering blog: Agent Skills https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
# Quality Checklist (Production Gate)
|
||||
|
||||
Use this checklist to decide whether a Skill is shippable. It is intentionally biased toward reliability and maintainability over "more content".
|
||||
|
||||
## Scoring
|
||||
|
||||
Score each item:
|
||||
- 2 = fully satisfied
|
||||
- 1 = partially satisfied / needs work
|
||||
- 0 = missing
|
||||
|
||||
Suggested ship threshold:
|
||||
- Total score >= 24 (out of 32)
|
||||
- No "critical" item below 2
|
||||
|
||||
## A. Activation Reliability (Critical)
|
||||
|
||||
1. Frontmatter `name` matches `^[a-z][a-z0-9-]*$` and matches directory name (2)
|
||||
2. Frontmatter `description` is decidable ("what + when") with concrete keywords (2)
|
||||
3. `## When to Use This Skill` lists concrete tasks/inputs/goals (2)
|
||||
4. `## Not For / Boundaries` exists and meaningfully prevents misfires (2)
|
||||
|
||||
## B. Usability (Critical)
|
||||
|
||||
5. `## Quick Reference` is short and directly usable (no doc dumps) (2)
|
||||
6. Quick Reference patterns are formatted for copy/paste (2)
|
||||
7. `## Examples` contains >= 3 reproducible examples (2)
|
||||
8. Examples include acceptance criteria / expected output (2)
|
||||
|
||||
## C. Evidence & Correctness
|
||||
|
||||
9. `## Maintenance` lists sources (docs/repos/specs) and last-updated date (2)
|
||||
10. Uncertain external details include a verification path (2)
|
||||
11. Terminology is consistent (one concept, one name) (2)
|
||||
12. No contradictions between Quick Reference and Examples (2)
|
||||
|
||||
## D. Structure & Maintainability
|
||||
|
||||
13. Long-form content lives in `references/` with `references/index.md` navigation (2)
|
||||
14. Reference files are split by topic (not one giant file) (2)
|
||||
15. The skill reads like an operator manual (task -> steps -> acceptance) (2)
|
||||
16. Optional: scripts/assets are minimal and clearly scoped (2)
|
||||
|
||||
## Common Reasons to Fail the Gate
|
||||
|
||||
- Vague activation ("helps with X") with no boundaries
|
||||
- Quick Reference contains pasted documentation instead of patterns
|
||||
- Examples are not reproducible (no inputs, no steps, no expected output)
|
||||
- No sources and no update date (cannot be trusted or maintained)
|
||||
@@ -0,0 +1,111 @@
|
||||
# Skill Spec (This Repo)
|
||||
|
||||
This document defines what a "production-grade Skill" means in this repository. Use it as the source of truth when creating or refactoring anything under `skills/`.
|
||||
|
||||
Keywords: MUST / SHOULD / MAY / MUST NOT / SHOULD NOT are normative.
|
||||
|
||||
## 1. Directory & Naming
|
||||
|
||||
- A Skill MUST be a directory under `skills/` named after its `name` field.
|
||||
- The directory name MUST match `^[a-z][a-z0-9-]*$`.
|
||||
- The Skill entrypoint MUST be `SKILL.md` at the root of the skill directory.
|
||||
|
||||
## 2. Frontmatter (Required)
|
||||
|
||||
`SKILL.md` MUST start with YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: "What it does + when to use (activation triggers)."
|
||||
---
|
||||
```
|
||||
|
||||
Rules:
|
||||
- `name` MUST match `^[a-z][a-z0-9-]*$`.
|
||||
- `name` SHOULD equal the directory name.
|
||||
- `description` MUST be decidable and operational:
|
||||
- Good: "X development and debugging. Use when doing A/B/C."
|
||||
- Bad: "Helps with X."
|
||||
|
||||
## 3. SKILL.md Structure
|
||||
|
||||
### 3.1 Required Sections
|
||||
|
||||
`SKILL.md` SHOULD follow this section order, and in strict mode it MUST:
|
||||
|
||||
1. `## When to Use This Skill`
|
||||
2. `## Not For / Boundaries`
|
||||
3. `## Quick Reference`
|
||||
4. `## Examples`
|
||||
5. `## References`
|
||||
6. `## Maintenance`
|
||||
|
||||
Rationale:
|
||||
- Activation reliability depends on explicit triggers and boundaries.
|
||||
- Usability depends on short patterns and reproducible examples.
|
||||
- Maintainability depends on sources and navigable references.
|
||||
|
||||
### 3.2 Quick Reference Rules
|
||||
|
||||
- Quick Reference MUST contain short, directly usable patterns.
|
||||
- Quick Reference MUST NOT become a documentation dump.
|
||||
- Long explanations SHOULD go to `references/`.
|
||||
- A good target is <= 20 patterns, but large domains may justify more.
|
||||
|
||||
### 3.3 Example Rules
|
||||
|
||||
- The Examples section MUST contain reproducible examples.
|
||||
- Each example SHOULD specify:
|
||||
- input(s)
|
||||
- steps
|
||||
- expected output / acceptance criteria
|
||||
- Pseudo-code MAY be used only if the platform is unavailable, and MUST be clearly labeled.
|
||||
|
||||
### 3.4 Boundaries Rules
|
||||
|
||||
- "Not For / Boundaries" MUST list:
|
||||
- explicit out-of-scope items (to prevent misfires)
|
||||
- required inputs and what to ask when missing (1-3 questions)
|
||||
|
||||
## 4. references/ (Long-form Docs)
|
||||
|
||||
- `references/` SHOULD exist when the domain has:
|
||||
- long docs
|
||||
- many edge cases
|
||||
- extensive APIs/CLIs/config surfaces
|
||||
- If `references/` exists, it SHOULD include:
|
||||
- `references/index.md` as a navigation entrypoint
|
||||
|
||||
Guideline:
|
||||
- `references/` is for evidence, depth, and navigation.
|
||||
- `SKILL.md` is for execution: short patterns + examples + constraints.
|
||||
|
||||
## 5. scripts/ and assets/
|
||||
|
||||
- `scripts/` MAY contain helper automation (generators, validators, setup).
|
||||
- Scripts MUST be non-interactive by default.
|
||||
- Scripts MUST NOT require network access unless explicitly stated.
|
||||
- `assets/` MAY contain templates, configs, or static resources.
|
||||
|
||||
## 6. Safety & Integrity
|
||||
|
||||
- Skills MUST NOT include secrets (API keys, tokens, credentials).
|
||||
- Skills MUST NOT invent external facts.
|
||||
- If uncertain, they MUST include a verification path (where/how to check).
|
||||
- Potentially destructive commands MUST be explicitly labeled and gated.
|
||||
|
||||
## 7. Maintenance Metadata
|
||||
|
||||
Each Skill SHOULD include a `## Maintenance` section with:
|
||||
- sources (docs/repos/specs)
|
||||
- last-updated date
|
||||
- known limits / non-goals
|
||||
|
||||
## 8. Quality Gate
|
||||
|
||||
Before shipping, run the checklist in `quality-checklist.md` and (if available) the validator:
|
||||
|
||||
```bash
|
||||
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name> --strict
|
||||
```
|
||||
Regular → Executable
+157
-166
@@ -1,190 +1,181 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# create-skill.sh - Production-grade Skill directory generator
|
||||
#
|
||||
# Usage: ./create-skill.sh <skill-name> [--minimal]
|
||||
#
|
||||
# Examples:
|
||||
# ./create-skill.sh postgresql
|
||||
# ./create-skill.sh my-api --minimal
|
||||
#
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -e
|
||||
set -euo pipefail
|
||||
|
||||
SKILL_NAME=$1
|
||||
MINIMAL=$2
|
||||
# ==================== Help ====================
|
||||
|
||||
if [ -z "$SKILL_NAME" ]; then
|
||||
echo "Usage: ./create-skill.sh <skill-name> [--minimal]"
|
||||
echo ""
|
||||
echo "Examples:"
|
||||
echo " ./create-skill.sh postgresql"
|
||||
echo " ./create-skill.sh my-api --minimal"
|
||||
exit 1
|
||||
usage() {
|
||||
cat <<'EOF'
|
||||
Usage:
|
||||
create-skill.sh <skill-name> [--minimal|--full] [--output <dir>] [--force]
|
||||
|
||||
Notes:
|
||||
- <skill-name> MUST be lowercase, start with a letter, and only contain letters, digits, and hyphens
|
||||
- Default mode: --full
|
||||
- Default output: current directory (creates ./<skill-name>/)
|
||||
|
||||
Examples:
|
||||
./skills/claude-skills/scripts/create-skill.sh postgresql --full --output skills
|
||||
./skills/claude-skills/scripts/create-skill.sh my-api --minimal
|
||||
EOF
|
||||
}
|
||||
|
||||
die() {
|
||||
echo "Error: $*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
# ==================== Arg Parsing ====================
|
||||
|
||||
skill_name=""
|
||||
mode="full"
|
||||
output_dir="."
|
||||
force=0
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-h|--help)
|
||||
usage
|
||||
exit 0
|
||||
;;
|
||||
--minimal)
|
||||
mode="minimal"
|
||||
shift
|
||||
;;
|
||||
--full)
|
||||
mode="full"
|
||||
shift
|
||||
;;
|
||||
-o|--output)
|
||||
[[ $# -ge 2 ]] || die "--output requires a directory argument"
|
||||
output_dir="$2"
|
||||
shift 2
|
||||
;;
|
||||
-f|--force)
|
||||
force=1
|
||||
shift
|
||||
;;
|
||||
--)
|
||||
shift
|
||||
break
|
||||
;;
|
||||
-*)
|
||||
die "Unknown argument: $1 (use --help)"
|
||||
;;
|
||||
*)
|
||||
if [[ -z "$skill_name" ]]; then
|
||||
skill_name="$1"
|
||||
shift
|
||||
else
|
||||
die "Extra argument: $1 (only one <skill-name> is allowed)"
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
[[ -n "$skill_name" ]] || { usage; exit 1; }
|
||||
|
||||
if [[ ! "$skill_name" =~ ^[a-z][a-z0-9-]*$ ]]; then
|
||||
die "skill-name must be lowercase, start with a letter, and only contain letters/digits/hyphens (e.g. my-skill-name)"
|
||||
fi
|
||||
|
||||
# Validate skill name (lowercase, hyphens only)
|
||||
if [[ ! "$SKILL_NAME" =~ ^[a-z][a-z0-9-]*$ ]]; then
|
||||
echo "Error: Skill name must be lowercase, start with letter, use hyphens"
|
||||
echo "Example: my-skill-name"
|
||||
exit 1
|
||||
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
|
||||
assets_dir="${script_dir}/../assets"
|
||||
|
||||
template_path=""
|
||||
case "$mode" in
|
||||
minimal) template_path="${assets_dir}/template-minimal.md" ;;
|
||||
full) template_path="${assets_dir}/template-complete.md" ;;
|
||||
*) die "Internal error: unknown mode=$mode" ;;
|
||||
esac
|
||||
|
||||
[[ -f "$template_path" ]] || die "Template not found: $template_path"
|
||||
|
||||
mkdir -p "$output_dir"
|
||||
|
||||
target_dir="${output_dir%/}/${skill_name}"
|
||||
|
||||
if [[ -e "$target_dir" && "$force" -ne 1 ]]; then
|
||||
die "Target already exists: $target_dir (use --force to overwrite)"
|
||||
fi
|
||||
|
||||
echo "Creating skill: $SKILL_NAME"
|
||||
mkdir -p "$target_dir"/{assets,scripts,references}
|
||||
|
||||
# Create directory structure
|
||||
mkdir -p "$SKILL_NAME"/{assets,scripts,references}
|
||||
# ==================== Write Files ====================
|
||||
|
||||
# Create references/index.md
|
||||
cat > "$SKILL_NAME/references/index.md" << 'EOF'
|
||||
# Documentation Index
|
||||
render_template() {
|
||||
local src="$1"
|
||||
local dest="$2"
|
||||
sed "s/{{skill_name}}/${skill_name}/g" "$src" > "$dest"
|
||||
}
|
||||
|
||||
## Categories
|
||||
render_template "$template_path" "$target_dir/SKILL.md"
|
||||
|
||||
### Getting Started
|
||||
- **getting_started.md** - Installation and setup
|
||||
|
||||
### API Reference
|
||||
- **api.md** - Complete API documentation
|
||||
|
||||
### Examples
|
||||
- **examples.md** - Code examples by use case
|
||||
cat > "$target_dir/references/index.md" <<EOF
|
||||
# ${skill_name} Reference Index
|
||||
|
||||
## Quick Links
|
||||
|
||||
- Installation → `getting_started.md`
|
||||
- API Reference → `api.md`
|
||||
- Examples → `examples.md`
|
||||
EOF
|
||||
|
||||
if [ "$MINIMAL" == "--minimal" ]; then
|
||||
# Minimal template
|
||||
cat > "$SKILL_NAME/SKILL.md" << EOF
|
||||
---
|
||||
name: $SKILL_NAME
|
||||
description: [Domain] assistance including [key capability]. Use when [trigger condition].
|
||||
---
|
||||
|
||||
# ${SKILL_NAME^} Skill
|
||||
|
||||
[One-sentence overview]
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
This skill should be triggered when:
|
||||
- [Trigger 1]
|
||||
- [Trigger 2]
|
||||
- [Trigger 3]
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**Pattern 1:**
|
||||
\`\`\`
|
||||
[code]
|
||||
\`\`\`
|
||||
|
||||
## Resources
|
||||
|
||||
### references/
|
||||
Documentation files
|
||||
|
||||
### scripts/
|
||||
Helper scripts
|
||||
EOF
|
||||
else
|
||||
# Full production template
|
||||
cat > "$SKILL_NAME/SKILL.md" << EOF
|
||||
---
|
||||
name: $SKILL_NAME
|
||||
description: [Domain] development including [capability 1], [capability 2]. Use when working with [domain], implementing solutions, or troubleshooting issues.
|
||||
---
|
||||
|
||||
# ${SKILL_NAME^} Skill
|
||||
|
||||
Comprehensive assistance with [domain] development.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
This skill should be triggered when:
|
||||
- Working with [domain/technology]
|
||||
- Asking about [domain] features or APIs
|
||||
- Implementing [domain] solutions
|
||||
- Debugging [domain] code
|
||||
- Learning [domain] best practices
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**Pattern 1:** [Name]
|
||||
\`\`\`
|
||||
[code example]
|
||||
\`\`\`
|
||||
|
||||
**Pattern 2:** [Name]
|
||||
\`\`\`
|
||||
[code example]
|
||||
\`\`\`
|
||||
|
||||
### Example Code Patterns
|
||||
|
||||
**Example 1:**
|
||||
\`\`\`
|
||||
[complete working code]
|
||||
\`\`\`
|
||||
|
||||
## Reference Files
|
||||
|
||||
This skill includes documentation in \`references/\`:
|
||||
|
||||
- **index.md** - Documentation navigation
|
||||
- **getting_started.md** - Setup and basics
|
||||
- **api.md** - API reference
|
||||
- **examples.md** - Code examples
|
||||
|
||||
## Working with This Skill
|
||||
|
||||
### For Beginners
|
||||
Start with getting_started reference file.
|
||||
|
||||
### For Specific Features
|
||||
Use api reference for detailed information.
|
||||
|
||||
### For Code Examples
|
||||
See examples reference file.
|
||||
|
||||
## Resources
|
||||
|
||||
### references/
|
||||
Organized documentation from official sources.
|
||||
|
||||
### scripts/
|
||||
Helper scripts for automation.
|
||||
|
||||
### assets/
|
||||
Templates and configurations.
|
||||
- Getting started: \`getting_started.md\`
|
||||
- API/CLI/config: \`api.md\` (if applicable)
|
||||
- Examples: \`examples.md\`
|
||||
- Troubleshooting: \`troubleshooting.md\`
|
||||
|
||||
## Notes
|
||||
|
||||
- Generated from official documentation
|
||||
- Code examples are complete and working
|
||||
- Put long-form content here: excerpts, evidence links, edge cases, FAQ
|
||||
- Keep \`SKILL.md\` Quick Reference short and directly usable
|
||||
EOF
|
||||
|
||||
if [[ "$mode" == "full" ]]; then
|
||||
cat > "$target_dir/references/getting_started.md" <<'EOF'
|
||||
# Getting Started & Vocabulary
|
||||
|
||||
## Goals
|
||||
|
||||
- Define the 10 most important terms in this domain
|
||||
- Provide the shortest path from zero to working
|
||||
EOF
|
||||
|
||||
cat > "$target_dir/references/api.md" <<'EOF'
|
||||
# API / CLI / Config Reference (If Applicable)
|
||||
|
||||
## Suggested Structure
|
||||
|
||||
- Organize by use case, not alphabetically
|
||||
- Key parameters: defaults, boundaries, common misuse
|
||||
- Common errors: message -> cause -> fix steps
|
||||
EOF
|
||||
|
||||
cat > "$target_dir/references/examples.md" <<'EOF'
|
||||
# Long Examples
|
||||
|
||||
Put examples longer than ~20 lines here, split by use case:
|
||||
|
||||
- Use case 1: ...
|
||||
- Use case 2: ...
|
||||
EOF
|
||||
|
||||
cat > "$target_dir/references/troubleshooting.md" <<'EOF'
|
||||
# Troubleshooting & Edge Cases
|
||||
|
||||
Write as: symptom -> likely causes -> diagnosis -> fix.
|
||||
EOF
|
||||
fi
|
||||
|
||||
# ==================== Summary ====================
|
||||
|
||||
echo ""
|
||||
echo "✅ Created skill: $SKILL_NAME/"
|
||||
echo "OK: Skill generated: $target_dir/"
|
||||
echo ""
|
||||
echo " $SKILL_NAME/"
|
||||
echo " ├── SKILL.md"
|
||||
echo " ├── assets/"
|
||||
echo " ├── scripts/"
|
||||
echo " └── references/"
|
||||
echo " └── index.md"
|
||||
echo "Layout:"
|
||||
echo " $target_dir/"
|
||||
echo " |-- SKILL.md"
|
||||
echo " |-- assets/"
|
||||
echo " |-- scripts/"
|
||||
echo " \\-- references/"
|
||||
echo " \\-- index.md"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo " 1. Edit $SKILL_NAME/SKILL.md"
|
||||
echo " 2. Add documentation to references/"
|
||||
echo " 3. Add helper scripts to scripts/"
|
||||
echo " 4. Add templates to assets/"
|
||||
echo " 1) Edit $target_dir/SKILL.md (triggers/boundaries/quick reference/examples)"
|
||||
echo " 2) Put long-form docs into $target_dir/references/ and update index.md"
|
||||
|
||||
+212
@@ -0,0 +1,212 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
cat <<'EOF'
|
||||
Usage:
|
||||
validate-skill.sh <skill-dir> [--strict]
|
||||
|
||||
What it does:
|
||||
- Validates SKILL.md YAML frontmatter (name/description)
|
||||
- Performs lightweight structural checks
|
||||
- In --strict mode, enforces the recommended section layout
|
||||
|
||||
Examples:
|
||||
./skills/claude-skills/scripts/validate-skill.sh skills/postgresql
|
||||
./skills/claude-skills/scripts/validate-skill.sh skills/my-skill --strict
|
||||
EOF
|
||||
}
|
||||
|
||||
die() {
|
||||
echo "Error: $*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
warn() {
|
||||
echo "Warning: $*" >&2
|
||||
}
|
||||
|
||||
strict=0
|
||||
skill_dir=""
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-h|--help)
|
||||
usage
|
||||
exit 0
|
||||
;;
|
||||
--strict)
|
||||
strict=1
|
||||
shift
|
||||
;;
|
||||
--)
|
||||
shift
|
||||
break
|
||||
;;
|
||||
-*)
|
||||
die "Unknown argument: $1 (use --help)"
|
||||
;;
|
||||
*)
|
||||
if [[ -z "$skill_dir" ]]; then
|
||||
skill_dir="$1"
|
||||
shift
|
||||
else
|
||||
die "Extra argument: $1 (only one <skill-dir> is allowed)"
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
[[ -n "$skill_dir" ]] || { usage; exit 1; }
|
||||
[[ -d "$skill_dir" ]] || die "Not a directory: $skill_dir"
|
||||
|
||||
skill_md="$skill_dir/SKILL.md"
|
||||
[[ -f "$skill_md" ]] || die "Missing SKILL.md: $skill_md"
|
||||
|
||||
base_name="$(basename -- "${skill_dir%/}")"
|
||||
|
||||
# -------------------- Parse YAML frontmatter --------------------
|
||||
|
||||
frontmatter=""
|
||||
if frontmatter="$(
|
||||
awk '
|
||||
BEGIN { in_fm=0; closed=0 }
|
||||
NR==1 {
|
||||
if ($0 != "---") exit 2
|
||||
in_fm=1
|
||||
next
|
||||
}
|
||||
in_fm==1 {
|
||||
if ($0 == "---") { closed=1; exit 0 }
|
||||
print
|
||||
next
|
||||
}
|
||||
END {
|
||||
if (closed == 0) exit 3
|
||||
}
|
||||
' "$skill_md"
|
||||
)"; then
|
||||
:
|
||||
else
|
||||
rc=$?
|
||||
case "$rc" in
|
||||
2) die "SKILL.md must start with YAML frontmatter (--- as the first line)" ;;
|
||||
3) die "YAML frontmatter is not closed (missing ---)" ;;
|
||||
*) die "Failed to parse YAML frontmatter (awk exit=$rc)" ;;
|
||||
esac
|
||||
fi
|
||||
|
||||
name="$(
|
||||
printf "%s\n" "$frontmatter" | awk -F: '
|
||||
tolower($1) ~ /^name$/ {
|
||||
sub(/^[^:]*:[[:space:]]*/, "", $0)
|
||||
gsub(/[[:space:]]+$/, "", $0)
|
||||
print
|
||||
exit
|
||||
}
|
||||
'
|
||||
)"
|
||||
|
||||
description="$(
|
||||
printf "%s\n" "$frontmatter" | awk -F: '
|
||||
tolower($1) ~ /^description$/ {
|
||||
sub(/^[^:]*:[[:space:]]*/, "", $0)
|
||||
gsub(/[[:space:]]+$/, "", $0)
|
||||
print
|
||||
exit
|
||||
}
|
||||
'
|
||||
)"
|
||||
|
||||
[[ -n "$name" ]] || die "Missing frontmatter field: name"
|
||||
[[ -n "$description" ]] || die "Missing frontmatter field: description"
|
||||
|
||||
if [[ ! "$name" =~ ^[a-z][a-z0-9-]*$ ]]; then
|
||||
die "Invalid name: '$name' (expected ^[a-z][a-z0-9-]*$)"
|
||||
fi
|
||||
|
||||
if [[ "$strict" -eq 1 && "$name" != "$base_name" ]]; then
|
||||
die "Strict mode: frontmatter name ('$name') must match directory name ('$base_name')"
|
||||
fi
|
||||
|
||||
# -------------------- Strip fenced code blocks for section checks --------------------
|
||||
|
||||
filtered_md="$(mktemp)"
|
||||
trap 'rm -f "$filtered_md"' EXIT
|
||||
|
||||
awk '
|
||||
BEGIN { in_fence=0 }
|
||||
/^[[:space:]]*```/ { in_fence = !in_fence; next }
|
||||
in_fence==0 { print }
|
||||
' "$skill_md" > "$filtered_md"
|
||||
|
||||
# -------------------- Structural checks --------------------
|
||||
|
||||
required_h2=(
|
||||
"When to Use This Skill"
|
||||
"Not For / Boundaries"
|
||||
"Quick Reference"
|
||||
"Examples"
|
||||
"References"
|
||||
"Maintenance"
|
||||
)
|
||||
|
||||
for title in "${required_h2[@]}"; do
|
||||
if ! grep -Eq "^##[[:space:]]+${title}([[:space:]]*)$" "$filtered_md"; then
|
||||
if [[ "$strict" -eq 1 ]]; then
|
||||
die "Strict mode: missing required section heading: '## ${title}'"
|
||||
fi
|
||||
warn "Missing recommended section heading: '## ${title}'"
|
||||
fi
|
||||
done
|
||||
|
||||
# references/index.md presence (only enforced in strict mode when references/ exists)
|
||||
if [[ -d "$skill_dir/references" && "$strict" -eq 1 && ! -f "$skill_dir/references/index.md" ]]; then
|
||||
die "Strict mode: references/ exists but references/index.md is missing"
|
||||
fi
|
||||
|
||||
# -------------------- Heuristics: Quick Reference size --------------------
|
||||
|
||||
quick_start="$(awk 'match($0, /^##[[:space:]]+Quick Reference([[:space:]]*)$/){print NR; exit}' "$filtered_md" || true)"
|
||||
if [[ -n "$quick_start" ]]; then
|
||||
quick_end="$(awk -v s="$quick_start" 'NR>s && match($0, /^##[[:space:]]+/){print NR; exit}' "$filtered_md" || true)"
|
||||
total_lines="$(wc -l < "$filtered_md" | tr -d ' ')"
|
||||
if [[ -z "$quick_end" ]]; then
|
||||
quick_end="$((total_lines + 1))"
|
||||
fi
|
||||
quick_len="$((quick_end - quick_start - 1))"
|
||||
if [[ "$quick_len" -gt 250 ]]; then
|
||||
if [[ "$strict" -eq 1 ]]; then
|
||||
die "Strict mode: Quick Reference section is too long (${quick_len} lines). Move long-form text into references/."
|
||||
fi
|
||||
warn "Quick Reference section is large (${quick_len} lines). Consider moving long-form text into references/."
|
||||
fi
|
||||
fi
|
||||
|
||||
# -------------------- Heuristics: Examples count --------------------
|
||||
|
||||
examples_start="$(awk 'match($0, /^##[[:space:]]+Examples([[:space:]]*)$/){print NR; exit}' "$filtered_md" || true)"
|
||||
if [[ -n "$examples_start" ]]; then
|
||||
examples_end="$(awk -v s="$examples_start" 'NR>s && match($0, /^##[[:space:]]+/){print NR; exit}' "$filtered_md" || true)"
|
||||
total_lines="$(wc -l < "$filtered_md" | tr -d ' ')"
|
||||
if [[ -z "$examples_end" ]]; then
|
||||
examples_end="$((total_lines + 1))"
|
||||
fi
|
||||
|
||||
example_count="$(
|
||||
awk -v s="$examples_start" -v e="$examples_end" '
|
||||
NR>s && NR<e && match($0, /^###[[:space:]]+Example([[:space:]]|$)/) { c++ }
|
||||
END { print c+0 }
|
||||
' "$filtered_md"
|
||||
)"
|
||||
|
||||
if [[ "$example_count" -lt 3 ]]; then
|
||||
if [[ "$strict" -eq 1 ]]; then
|
||||
die "Strict mode: expected >= 3 examples (found ${example_count})."
|
||||
fi
|
||||
warn "Recommended: >= 3 examples (found ${example_count})."
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "OK: $skill_dir"
|
||||
Reference in New Issue
Block a user