create-skill

Create Skill

Use this skill when the user asks to create a skill, make a skill, add a new skill, or similar requests.

When to Use

Trigger when user mentions:

• "create a skill"
• "make a skill"
• "add a new skill"
• "write a skill"
• "scaffold a skill"
• "set up a skill"

Step 1: Clarify Skill Type

Always ask the user which type of skill they want to create:

Type	Location	Visibility	Use Case
Personal	~/.adal/skills/<name>/	Only you	Custom workflows, personal preferences
Project	.adal/skills/<name>/	Team (via git)	Team conventions, project-specific patterns
Plugin	GitHub repo	Public	Community-shareable, reusable across projects

Example prompt:

What type of skill would you like to create?

1. Personal skill (~/.adal/skills/) - Just for you, not shared
2. Project skill (.adal/skills/) - Shared with your team via git
3. Plugin skill (GitHub repo) - Public, shareable with the community

Which type? (1/2/3)

Step 2: Gather Skill Details

Ask for:

1. Skill name - lowercase, hyphenated (e.g., my-workflow, team-conventions)
2. Description - Brief explanation of what it does and when to use it
3. When to trigger - Keywords or scenarios that should activate this skill

Step 3: Create the Skill Structure

For Personal Skills (~/.adal/skills/)

mkdir -p ~/.adal/skills/<skill-name>

Create SKILL.md with required YAML frontmatter:

---
name: <skill-name>
description: <Brief description>
author: <your-name or org>
version: 1.0.0
---

# <Skill Title>

## When to Use
<Describe trigger scenarios>

## Instructions
<Step-by-step guidance for the agent>

⚠️ REQUIRED: The --- YAML frontmatter block is mandatory. Skills without it will fail to load. At minimum, include name and description.

For Project Skills (.adal/skills/)

mkdir -p .adal/skills/<skill-name>

Same SKILL.md format. Remember to commit to git for team sharing.

For Plugin Skills (GitHub)

1. Create a GitHub repository with this structure:

   <repo>/
   ├── .claude-plugin/
   │   └── marketplace.json     # Required location for Claude Code compatibility
   ├── skills/
   │   └── <skill-name>/
   │       └── SKILL.md
   └── README.md
   

2. marketplace.json (MUST be in .claude-plugin/ directory):

   {
     "name": "my-marketplace-name",
     "owner": {
       "name": "Your Name or Org",
       "email": "contact@example.com"
     },
     "metadata": {
       "description": "My collection of skills",
       "version": "1.0.0"
     },
     "plugins": [
       {
         "name": "my-plugin",
         "description": "Plugin description",
         "source": "./",
         "skills": ["./skills/skill-name"]
       }
     ]
   }
   

   Critical fields:

   • owner: Object with name and email (required by Claude Code)
   • metadata: Wrapper for description and version
   • plugins[].source: Path to skills root (use "./" for repo root)
   • plugins[].skills: Two formats supported:
     • Array (explicit): ["./skills/xlsx", "./skills/docx"] - list specific skill directories
     • String (scan): "skills" or "./" - recursively scan for SKILL.md files

3. Installation commands:

   # Add marketplace
   /plugin marketplace add <owner>/<repo>
   
   # Direct install (marketplace-name from marketplace.json "name" field)
   /plugin install <plugin-name>@<marketplace-name>
   

4. IMPORTANT: Keep marketplace.json in sync!

   Every time you add a new skill to the plugin, update the skills array in marketplace.json:

   "skills": ["./skills/create-skill", "./skills/new-skill-name"]
   

   Without this, the skill won't be discoverable via /skills command after plugin installation.

Step 4: Verify Installation

After creating:

• Run /skills to verify the skill appears
• Test by asking the agent to perform a task the skill should handle

Advanced Options

If the user wants multi-file skills, guide them on:

• REFERENCE.md - Detailed documentation
• scripts/ - Executable utilities (Python, bash)
• Link supporting files from SKILL.md

Example Interaction

User: "Create a skill for our API conventions"

Agent: "What type of skill would you like?

1. Personal - just for you
2. Project - shared with team via git
3. Plugin - public on GitHub"

User: "Project"

Agent: "I'll create .adal/skills/api-conventions/. What conventions should it include?"