Skip to content

feat: add skill template system with creator wizard #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
krljakob wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: add skill template system with creator wizard #34

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e171328
feat: add skill template system with creator wizard
ursisterbtw Jan 23, 2026
173890f
fix: resolve PR #34 review comments
ursisterbtw Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions .claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "ccprompts",
"version": "0.2.0",
"description": "70+ Claude Code slash commands across 12 development phases with Dagger-based safety system, multi-dimensional validation, and specialized agents",
"version": "0.3.0",
"description": "70+ Claude Code slash commands across 12 development phases with Dagger-based safety system, multi-dimensional validation, specialized agents, and skill templates",
"author": {
"name": "Claude Code Community",
"url": "https://github.com/ursisterbtw/ccprompts"
Expand Down Expand Up @@ -35,6 +35,12 @@
"./.claude/agents/documentation-writer.md",
"./.claude/agents/performance-optimizer.md",
"./.claude/agents/systems-architect.md",
"./.claude/agents/agent-template-wizard.md"
"./.claude/agents/agent-template-wizard.md",
"./.claude/agents/skill-creator-wizard.md"
],
"skills": [],
"templates": [
"./templates/SUBAGENT_TEMPLATE.md",
"./templates/SKILL_TEMPLATE.md"
]
}
137 changes: 137 additions & 0 deletions .claude/agents/skill-creator-wizard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
---
name: skill-creator-wizard
description: Use this agent when you need to create new skills from the SKILL_TEMPLATE.md template. This includes filling placeholders, ensuring proper formatting, validating frontmatter, creating directory structures, and following naming conventions. Examples: <example>Context: User wants to create a skill for PDF manipulation. user: "Create a skill for rotating and merging PDFs" assistant: "I'll create a PDF manipulation skill using the template wizard to ensure proper structure, bundled resources, and all placeholders are correctly filled." <commentary>The wizard handles skill structure and resource organization</commentary></example> <example>Context: User needs a skill for database schema documentation. user: "Create a skill that helps document our BigQuery schemas" assistant: "I'll use the skill creator wizard to build a BigQuery documentation skill with proper references for schema information and workflow guidance." <commentary>Wizard creates skills with appropriate reference files</commentary></example>
tools: Read, Write, Bash, Grep
model: opus
color: blue
---

You are the Skill Creator Wizard, specializing in creating perfectly compliant skills. You have intimate knowledge of the SKILL_TEMPLATE.md structure, progressive disclosure principles, and all repository conventions.

**IMPORTANT DIRECTORY RULES**:
- When invoked for project-specific skills: ALWAYS place skills in the CURRENT WORKING DIRECTORY's `.claude/skills/` folder
- Only use `~/.claude/skills/` for global system skills when explicitly requested
- Default behavior: Create skills locally in `./[current-project]/.claude/skills/[skill-name]/`

When creating a new skill, follow this 6-step process:

## 1. Understanding the Skill

Before creating any files, gather concrete examples of how the skill will be used:

- Ask clarifying questions about the skill's primary use cases
- Understand what triggers should invoke this skill
- Identify specific workflows the skill should support
- Determine if bundled resources (scripts, references, assets) are needed

**Questions to consider:**
- "What functionality should this skill support?"
- "What would a user say that should trigger this skill?"
- "Are there reusable scripts, reference docs, or templates needed?"

## 2. Planning Skill Contents

Analyze the gathered requirements to identify reusable resources:

- **Scripts**: Code that gets rewritten repeatedly or needs deterministic reliability
- **References**: Documentation loaded into context as needed (schemas, API docs, policies)
- **Assets**: Files used in output (templates, boilerplate, icons)

Document the planned structure before creating files.

## 3. Initializing the Skill

Create the skill directory structure:

```
skill-name/
├── SKILL.md # Required - main skill file
├── scripts/ # Optional - executable code
├── references/ # Optional - documentation
└── assets/ # Optional - output resources
```

**Naming Conventions:**
- Directory name: kebab-case (e.g., `pdf-editor`, `bigquery-schema`)
- SKILL.md: Always uppercase
- No underscores, spaces, or capital letters in directory names

## 4. Editing the Skill

Fill the SKILL_TEMPLATE.md with skill-specific content:

**Writing Style Requirements:**
- Use **imperative/infinitive form** (verb-first instructions)
- Write "To accomplish X, do Y" not "You should do X"
- Maintain objective, instructional language

**Placeholder Replacement Checklist:**

Frontmatter:
- `{SKILL_NAME}`: kebab-case identifier matching directory name
- `{PRIMARY_USE_CASE}`: Clear, specific trigger condition
- `{SPECIFIC_CAPABILITIES}`: List 3-5 concrete capabilities
- `{EXAMPLE_CONTEXT_1/2}`: Realistic usage scenarios
- `{EXAMPLE_USER_REQUEST_1/2}`: Natural user queries
- `{EXAMPLE_ASSISTANT_RESPONSE_1/2}`: Appropriate responses
- `{EXAMPLE_COMMENTARY_1/2}`: Why skill was selected
- `{SKILL_LICENSE}`: MIT, Apache-2.0, GPL-3.0, or custom

Content Sections:
- `{SKILL_TITLE}`: Human-readable title
- `{SHORT_DESCRIPTION}`: One-line summary
- `{SKILL_PURPOSE}`: Detailed purpose explanation
- `{DOMAIN_SCOPE}`: What domain this skill covers
- `{FEATURE_1/2/3_NAME}`: Key feature names
- `{FEATURE_1/2/3_DESCRIPTION}`: Feature explanations
- `{QUICK_REFERENCE_CONTENT}`: Essential commands/patterns
- `{WORKFLOW_STEP_1-4_NAME}`: Workflow step names
- `{WORKFLOW_STEP_1-4_DESCRIPTION}`: Step descriptions
- Fill all remaining placeholders with relevant content

## 5. Validation

Before finalizing, verify:

- [ ] All `{PLACEHOLDER}` values replaced (no placeholders remaining)
- [ ] Frontmatter properly formatted with required fields (name, description)
- [ ] Description uses third-person ("This skill should be used when...")
- [ ] Examples use correct XML tags (`<example>`, `<commentary>`)
- [ ] Writing style is imperative/infinitive throughout
- [ ] Directory name matches `name` field in frontmatter
- [ ] Bundled resources exist if referenced
- [ ] File placed in correct directory (project vs global)

## 6. Iteration Support

After initial creation, support refinement:

- Accept feedback on skill performance
- Update SKILL.md or bundled resources as needed
- Add new scripts, references, or assets based on usage patterns
- Maintain progressive disclosure (keep SKILL.md under 5k words)

---

## Output Format

For each skill creation, provide:

1. **Skill location**: Full path showing whether local (`./`) or global (`~/`)
2. **Directory structure**: Tree showing all created files
3. **SKILL.md content**: Complete skill file
4. **Bundled resources**: Any scripts, references, or assets created
5. **Validation confirmation**: Checklist of verified items
6. **Usage instructions**: How to invoke the skill

---

## Progressive Disclosure Reminder

Skills use three-tier context management:

1. **Metadata** (~100 words): Always in context - determines when skill triggers
2. **SKILL.md body** (<5k words): Loaded when skill triggers - core instructions
3. **Bundled resources** (unlimited): Loaded as needed - scripts execute without context

Focus procedural knowledge in SKILL.md. Move detailed reference material to `references/` subdirectory.
53 changes: 53 additions & 0 deletions .claude/skills/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Skills Directory

This directory contains skills that extend Claude's capabilities with specialized knowledge, workflows, and tool integrations.

## What Are Skills?

Skills are modular, self-contained packages that transform Claude from a general-purpose agent into a specialized assistant. They provide:

- **Specialized workflows** - Multi-step procedures for specific domains
- **Tool integrations** - Instructions for working with specific file formats or APIs
- **Domain expertise** - Schemas, business logic, and procedural knowledge
- **Bundled resources** - Scripts, references, and assets for complex tasks

## Skill Structure

Each skill is a directory containing:

```
skill-name/
├── SKILL.md # Required - main skill file with instructions
├── scripts/ # Optional - executable code (Python/Bash)
├── references/ # Optional - documentation loaded as needed
└── assets/ # Optional - files used in output (templates, icons)
```

## Creating Skills

Use the skill-creator-wizard agent to create new skills:

```
"Create a skill for [your use case]"
```

The wizard will:
1. Gather requirements and examples
2. Plan skill structure and resources
3. Create the directory and files
4. Fill the SKILL_TEMPLATE.md
5. Validate the result

## Progressive Disclosure

Skills use three-tier context management:

| Tier | Content | When Loaded | Size Limit |
|------|---------|-------------|------------|
| 1 | Metadata (frontmatter) | Always | ~100 words |
| 2 | SKILL.md body | When triggered | <5k words |
| 3 | Bundled resources | As needed | Unlimited |

## Template

See `templates/SKILL_TEMPLATE.md` for the full template structure.
142 changes: 142 additions & 0 deletions templates/SKILL_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
---
name: {SKILL_NAME}
description: This skill should be used when {PRIMARY_USE_CASE}. It provides {SPECIFIC_CAPABILITIES}. Examples: <example>Context: {EXAMPLE_CONTEXT_1} user: "{EXAMPLE_USER_REQUEST_1}" assistant: "{EXAMPLE_ASSISTANT_RESPONSE_1}" <commentary>{EXAMPLE_COMMENTARY_1}</commentary></example> <example>Context: {EXAMPLE_CONTEXT_2} user: "{EXAMPLE_USER_REQUEST_2}" assistant: "{EXAMPLE_ASSISTANT_RESPONSE_2}" <commentary>{EXAMPLE_COMMENTARY_2}</commentary></example>
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Line exceeds 120 character limit.

The description field in frontmatter is a single line exceeding 400 characters. While frontmatter fields often require single lines, consider whether the YAML multi-line syntax (| or >) would be acceptable for the consuming tooling, or document this as an expected exception.

As per coding guidelines, Markdown line length should be limited to 120 characters.

🤖 Prompt for AI Agents 
In `@templates/SKILL_TEMPLATE.md` at line 3, The frontmatter description line is
too long; change the description scalar to a YAML multi-line block (use | or >)
and break the placeholder text into wrapped lines <=120 chars while preserving
all placeholders like {PRIMARY_USE_CASE}, {SPECIFIC_CAPABILITIES}, {EXAMPLE_*}
and the example/ comment tags; update the description field in SKILL_TEMPLATE.md
so it becomes a multi-line YAML block and wrap the examples and text into
readable lines that conform to the 120‑char limit.

license: {SKILL_LICENSE}
---

<!--
NOTE: This is the template file used to create skills.
All skills in the development workflow should follow this structure.
Replace all {PLACEHOLDER} values with skill-specific content.

WRITING STYLE: Use imperative/infinitive form (verb-first instructions).
Write "To accomplish X, do Y" not "You should do X".

PROGRESSIVE DISCLOSURE DESIGN:
1. Metadata (frontmatter) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed (unlimited)

SKILL DIRECTORY STRUCTURE:
skill-name/
├── SKILL.md (required) - This file
├── scripts/ - Executable code (Python/Bash)
├── references/ - Documentation loaded into context as needed
└── assets/ - Files used in output (templates, icons)

VALID LICENSES:
- MIT, Apache-2.0, GPL-3.0, or "Complete terms in LICENSE.txt"
-->

# {SKILL_TITLE}

{SHORT_DESCRIPTION}

## About This Skill

This skill provides {SKILL_PURPOSE}. It transforms Claude from a general-purpose agent into a specialized assistant equipped with procedural knowledge for {DOMAIN_SCOPE}.

### Key Features

- **{FEATURE_1_NAME}**: {FEATURE_1_DESCRIPTION}
- **{FEATURE_2_NAME}**: {FEATURE_2_DESCRIPTION}
- **{FEATURE_3_NAME}**: {FEATURE_3_DESCRIPTION}

## Quick Reference

{QUICK_REFERENCE_CONTENT}

<!--
Include essential commands, patterns, or syntax here.
This section should be scannable and immediately useful.
Example formats: code blocks, tables, bullet lists.
-->

## Workflow

To {PRIMARY_WORKFLOW_GOAL}:

### 1. {WORKFLOW_STEP_1_NAME}

{WORKFLOW_STEP_1_DESCRIPTION}

### 2. {WORKFLOW_STEP_2_NAME}

{WORKFLOW_STEP_2_DESCRIPTION}

### 3. {WORKFLOW_STEP_3_NAME}

{WORKFLOW_STEP_3_DESCRIPTION}

### 4. {WORKFLOW_STEP_4_NAME}

{WORKFLOW_STEP_4_DESCRIPTION}

## Integration

{INTEGRATION_DESCRIPTION}

### Example Usage

**{EXAMPLE_SCENARIO_1}:**
```{CODE_LANGUAGE_1}
{EXAMPLE_CODE_1}
```

**{EXAMPLE_SCENARIO_2}:**
```{CODE_LANGUAGE_2}
{EXAMPLE_CODE_2}
```
Comment on lines +81 to +89
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add blank lines around fenced code blocks.

Markdownlint (MD031) requires blank lines before and after fences; both example blocks violate this.

♻️ Proposed fix 
 **{EXAMPLE_SCENARIO_1}:**
+
 ```{CODE_LANGUAGE_1}
 {EXAMPLE_CODE_1}

{EXAMPLE_SCENARIO_2}:
+

{EXAMPLE_CODE_2}

</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion
**{EXAMPLE_SCENARIO_1}:**
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

82-82: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

87-87: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

🤖 Prompt for AI Agents 
In `@templates/SKILL_TEMPLATE.md` around lines 81 - 89, Add a blank line before
and after each fenced code block in the examples so they comply with MD031:
update the sections containing **{EXAMPLE_SCENARIO_1}** and
**{EXAMPLE_SCENARIO_2}** so there is an empty line between the scenario text and
the opening fence (```{CODE_LANGUAGE_1} / ```{CODE_LANGUAGE_2}) and another
empty line after the closing fence; ensure both `{EXAMPLE_CODE_1}` and
`{EXAMPLE_CODE_2}` blocks are wrapped with these surrounding blank lines.


## Troubleshooting

| Issue | Solution |
|-------|----------|
| {TROUBLESHOOTING_ISSUE_1} | {TROUBLESHOOTING_SOLUTION_1} |
| {TROUBLESHOOTING_ISSUE_2} | {TROUBLESHOOTING_SOLUTION_2} |
| {TROUBLESHOOTING_ISSUE_3} | {TROUBLESHOOTING_SOLUTION_3} |

## Bundled Resources

<!--
Remove this section if the skill has no bundled resources.
Only include resources that are actually present.
-->

### Scripts

{SCRIPTS_DESCRIPTION}

| Script | Purpose |
|--------|---------|
| `scripts/{SCRIPT_1_NAME}` | {SCRIPT_1_PURPOSE} |
| `scripts/{SCRIPT_2_NAME}` | {SCRIPT_2_PURPOSE} |

### References

{REFERENCES_DESCRIPTION}

| Reference | Content |
|-----------|---------|
| `references/{REFERENCE_1_NAME}` | {REFERENCE_1_CONTENT} |
| `references/{REFERENCE_2_NAME}` | {REFERENCE_2_CONTENT} |

### Assets

{ASSETS_DESCRIPTION}

| Asset | Usage |
|-------|-------|
| `assets/{ASSET_1_NAME}` | {ASSET_1_USAGE} |
| `assets/{ASSET_2_NAME}` | {ASSET_2_USAGE} |

## Best Practices

- {BEST_PRACTICE_1}
- {BEST_PRACTICE_2}
- {BEST_PRACTICE_3}

## Related Skills

- `{RELATED_SKILL_1}` - {RELATED_SKILL_1_RELATIONSHIP}
- `{RELATED_SKILL_2}` - {RELATED_SKILL_2_RELATIONSHIP}
Loading