agentleFS
AI-Shell-TeamAI-Shell-Team/aish/skills/aish-add-skills/SKILL.md

aish-add-skills

Skill578 starsChanged 6 months agoApache-2.0View on GitHub

Create new skills from documents, tutorials, or examples. Use when user wants to create a skill from learning materials or existing content.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 8
  2. Distinctive:

    Use Create Mode when:

    line 24
  3. Distinctive:

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

    line 64
  4. Distinctive:

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

    line 89
  5. Distinctive:

    Use descriptive names that reflect actual content

    line 94
  6. Very specific:

    Avoid generic names like template.md or sample.md

    line 95
  7. Distinctive:

    Always validate content suitability before extracting

    line 380
  8. Distinctive:

    Use descriptive file names that reflect actual content

    line 383
  9. Very specific:

    Keep SKILL.md under 500 lines - move detailed reference to supporting files

    line 384

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

TypeCharacteristicsExamples
How-toClear step sequence, input→outputDeploy Docker, Configure CI/CD
DecisionConditions, trade-offs, choicesChoose database, Select framework
FrameworkMental model, analysis dimensionsSWOT, 5W1H, First Principles
ChecklistVerification list, pass/fail criteriaCode review checklist, Launch checklist

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

DimensionQuestions
StructureHow is content organized?
StyleTone, word choice, expression?
TechniqueWhat methods make it effective?
LogicHow does information flow?
DetailsSmall but important touches?

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.