aish-add-skills

AISH Create Skills

Create reusable skills by extracting methodologies from learning materials or examples.

Quick Example

User: "根据这篇 Docker 教程创建一个 skill"

AI: 读取文档 → 提取步骤 → 生成 skill 结构 → 保存到 ~/.config/aish/skills/

---

Create Mode Overview

Extract actionable methodologies from learning materials or examples to generate reusable Skills.

When to Use

Use Create Mode when:

• User provides a document/article/tutorial
• User provides an example to learn from
• User says "根据这篇文章创建一个 skill"
• User says "从这个示例学习并创建 skill"

---

Step 0: Identify Input Type

Critical first step - determine which processing path:

User Input
    │
    ├─ Has teaching intent? ("how to", "steps", "guide")
    │   └─ YES → Path A: Methodology Document
    │
    ├─ Is a finished work? (article, design, code, proposal)
    │   └─ YES → Path B: Example (Reverse Engineering)
    │
    └─ Neither? → Tell user this content is not suitable

Path A indicators (Methodology Document):

• Contains "how to", "steps", "method", "guide"
• Has numbered lists or step sequences
• Written with teaching intent

Path B indicators (Example/Output):

• Is a complete work/artifact
• No teaching intent
• Is "the thing itself" rather than "how to make the thing"

---

Path A: Extract from Methodology Document

A1: Validate Document Suitability

Check if suitable for skill generation (must meet at least 2):

• Has clear goal/outcome
• Has repeatable steps/process
• Has quality criteria
• Has context/scenario description

If not suitable: Tell user honestly and explain why.

A2: Identify Skill Type

A3: Extract Structure by Type

For How-to: Prerequisites → Step sequence → Expected result → Common errors

For Decision: Decision factors → Options with pros/cons → Decision tree → Recommended default

For Framework: Core concepts → Analysis dimensions → Application method → Limitations

For Checklist: Check items with criteria → Priority levels → Commonly missed items

A4: Generate Skill Directory

File naming principles:

• Use descriptive names that reflect actual content
• Avoid generic names like template.md or sample.md

Create structure based on skill needs:

{skill-name}/
├── SKILL.md                      # Main instructions (required)
├── {descriptive-name}.md         # Reference docs (name by content)
├── examples/                     # Example outputs (descriptive names)
│   └── {example-description}.md
└── scripts/                      # Helper scripts (name by purpose)
    └── {script-purpose}.{py|sh}

Example for blog-post-writer skill:

blog-post-writer/
├── SKILL.md
├── structure-template.md   # Blog post structure template
├── examples/
│   ├── technical-post.md   # Example technical blog post
│   └── tutorial-post.md    # Example tutorial post
└── scripts/
    └── word-count.py       # Word counter script

A5: Write SKILL.md

Use this template:

---
name: {skill-name}
description: {What it does and when to use it}
---

# {Skill Name}

{Brief description}

## When to Use

Use this skill when:
- {Scenario 1}
- {Scenario 2}

## Prerequisites

- {Prerequisite 1}
- {Prerequisite 2}

## Steps

1. **{Step 1}** - {Expected outcome}
   - {Detail}

2. **{Step 2}** - {Expected outcome}
   - {Detail}

## Quality Checkpoints

- [ ] {Checkpoint 1}
- [ ] {Checkpoint 2}

## Common Pitfalls

- **{Pitfall 1}**: {How to avoid}

## Source

- Document: {name/URL}
- Extracted: {timestamp}

Reference supporting files:

## Additional Resources

- For detailed template, see [structure-template.md](structure-template.md)
- For examples, see [examples/](examples/)

A6: Save to Disk

SKILL_DIR=~/.config/aish/skills/{skill-name}

# Create directories only if needed
# mkdir -p "$SKILL_DIR/examples"
# mkdir -p "$SKILL_DIR/scripts"

# Write SKILL.md (required)
cat > "$SKILL_DIR/SKILL.md" << 'EOF'
{SKILL.md content}
EOF

# Write optional files with descriptive names

---

Path B: Reverse Engineer from Example

B1: Identify Output Type

What kind of artifact is this?

• Technical blog post
• Product proposal/PRD
• Academic paper
• Code architecture
• Design document
• Other: [specify]

B2: Analyze Structure

Structure Analysis:
├── [Part 1]: [Function] - [Proportion %]
├── [Part 2]: [Function] - [Proportion %]
└── [Part N]: [Function] - [Proportion %]

Questions:

• How many parts?
• What's the function of each part?
• What's the order and proportion?

B3: Extract Quality Characteristics

B4: Reverse Engineer Process

## Deduced Production Steps
1. [Step 1]: [What to do] - [Key point]
2. [Step 2]: [What to do] - [Key point]

## Key Decisions
- [Decision 1]: [Options] - [Chose X because...]

## Reusable Techniques
- [Technique 1]: [How to apply]

B5: Generate Skill Directory

Example for technical-blog-writer skill:

technical-blog-writer/
├── SKILL.md
├── blog-post-template.md   # Template for blog posts
├── examples/
│   └── react-hooks-post.md # The analyzed example
└── scripts/
    └── readability.py      # Readability checker

B6: Write SKILL.md

---
name: {skill-name}
description: {What it does}
---

# {Skill Name}

{Brief description}

## Output Type

{What kind of artifact this produces}

## When to Use

Use this skill when:
- {Scenario 1}
- {Scenario 2}

## Structure Template

1. [Part 1]: [Function] - [~X%]
2. [Part 2]: [Function] - [~X%]

## Quality Characteristics

Learned from example:
- [Characteristic 1]: [How it manifests]
- [Characteristic 2]: [How it manifests]

## Production Steps

1. **{Step 1}**: [What to do] - [Tips]
2. **{Step 2}**: [What to do] - [Tips]

## Checklist

- [ ] [Check item 1]
- [ ] [Check item 2]

## Reference Example

- Source: [name/URL]
- Analyzed: [timestamp]

## Additional Resources

- For template, see [blog-post-template.md](blog-post-template.md)
- For reference example, see [examples/react-hooks-post.md](examples/react-hooks-post.md)

B7: Save to Disk

SKILL_DIR=~/.config/aish/skills/{skill-name}

# Write SKILL.md
cat > "$SKILL_DIR/SKILL.md" << 'EOF'
{SKILL.md content}
EOF

# Write optional files with descriptive names

---

Skill Best Practices

File Naming

Good naming:

• api-reference.md (not reference.md)
• blog-post-template.md (not template.md)
• examples/react-hooks-post.md (not examples/sample.md)
• scripts/validate-readability.py (not scripts/helper.py)

Avoid generic names like: template.md, sample.md, original.md, helper.py

SKILL.md Guidelines

• Keep under 500 lines
• Focus on essentials in SKILL.md
• Move detailed reference to separate files
• Reference supporting files with markdown links

Frontmatter (Optional)

---
name: my-skill
description: What this skill does and when to use it
disable-model-invocation: true  # Only user can invoke
user-invocable: false            # Hide from / menu
allowed-tools: Read, Grep        # Restrict tool access
argument-hint: [filename]        # Autocomplete hint
---

Types of Skills

Reference content: Knowledge, conventions, patterns (runs inline)

• Example: API conventions, coding standards

Task content: Step-by-step instructions (often user-invoked)

• Example: Deploy, commit, code generation

---

Installation Path

Skills are saved to: ~/.config/aish/skills/

aish automatically hot-reloads skills from this directory.

---

Important Notes

1. Always validate content suitability before extracting
2. Take time to truly understand the content
3. Preserve sources - always credit where knowledge came from
4. Use descriptive file names that reflect actual content
5. Keep SKILL.md under 500 lines - move detailed reference to supporting files