Overview
Meta-skill that teaches agents how to integrate external skill repositories into the 1ai-skills library. Covers the full pipeline from discovery through validation, ensuring new skills are unique, properly formatted, correctly categorized, and quality-gated before merge.
Discovery
Before importing anything, understand what the external repo offers.
- Read the repo README for purpose, scope, and skill count
- Check if the repo uses SKILL.md files, AGENTS.md, or another structure
- List all skill files and extract their frontmatter (name, description, domain, tags)
- Identify the unique value — what does this repo offer that 1ai-skills does not already cover?
# List all potential skill files in the external repo
find /path/to/external-repo -name "SKILL.md" -o -name "*.md" | head -50
# Extract frontmatter from each
for f in $(find /path/to/external-repo -name "SKILL.md"); do
echo "=== $f ==="
sed -n '/^---$/,/^---$/p' "$f"
done
Deduplication
Always check for overlap before importing. Redundant skills degrade the library.
- Grep existing SKILLS.json for similar skill names:
grep -i "keyword" /home/openclaw/projects/1ai-skills/SKILLS.json
- Grep existing skills for similar descriptions:
grep -ri "description.*keyword" /home/openclaw/projects/1ai-skills/*/SKILL.md
- Check the target category's current count and capacity
- For each candidate skill, document: overlaps found, unique value, import decision (import / skip / merge)
Format Conversion
All 1ai-skills must follow the standard YAML frontmatter format.
Required frontmatter fields:
---
name: skill-name # kebab-case, unique across repo
description: What it does. Use when [trigger1], [trigger2]. # max ~200 chars
domain: category-name # must match an existing category directory
tags:
- [tag1
- tag2
- tag3] # 3-8 relevant tags
---
Conversion checklist:
Category Mapping
Map external skills to the existing 18 categories:
| Category |
Focus |
automation/ |
Bots, scrapers, pipelines, workflow automation |
agents/ |
Agent architectures, autonomous systems |
content/ |
Video, podcast, design, UI generation |
core/ |
Self-improvement, memory, orchestration, infrastructure |
cybersecurity/ |
Threat hunting, forensics, pen testing, SOC, compliance |
data/ |
Data cleaning, visualization, pipelines, reporting |
development/ |
TDD, debugging, code review, patterns, frameworks |
devops/ |
Docker, K8s, CI/CD, cloud ops, GitOps |
financial/ |
Finance analysis, investing, tax, accounting |
integrations/ |
Platform integrations (GitHub, Discord, Notion, Slack) |
marketing/ |
SEO, growth, email, social, affiliate |
mcp/ |
MCP server skills |
meta/ |
Self-improving meta-skills, skill management |
operations/ |
Governance, KYC, project management, HR, legal |
productivity/ |
Calendar, email, meetings, workspace tools |
research/ |
Analysis, deep research, competitive intelligence |
sales/ |
Lead gen, closing, B2B, CRM, influence |
trading/ |
Crypto, DeFi, strategies, smart contracts |
If no category fits: Propose a new category in the PR with justification. New categories need at least 3 skills to be viable.
Validation
Run the full validation pipeline after import.
# 1. Refresh the skill catalog
bash /home/openclaw/projects/1ai-skills/scripts/audit-skills.sh --write
# 2. Verify counts match
bash /home/openclaw/projects/1ai-skills/scripts/audit-skills.sh
# 3. Update documentation with new counts
# - README.md: skill count in header
# - llms.txt: category table
# - package.json: description field if count mentioned
# - AGENTS.md: category table
Quality Gates
Every imported skill must pass these gates before merge:
Gate 1 — Self-Contained: The skill is fully understandable without reading the source repo. No "see the README for details" — all details are in the SKILL.md.
Gate 2 — Actionable: The skill provides concrete steps, commands, code examples, or decision frameworks. Not just a description of what something is.
Gate 3 — Unique Value: No existing 1ai-skill covers the same ground. If there is overlap, the new skill must be clearly differentiated or merged into the existing one.
Gate 4 — Correct Format: YAML frontmatter is valid, required fields present, naming conventions followed, category mapping is correct.
Gate 5 — No Leaks: No hardcoded paths, API keys, user-specific config, or internal URLs. Safe for any user to install.
Process
1. Discovery → Read repo, list skills, extract metadata
2. Dedup → Grep existing skills, document overlaps
3. Convert → Apply format, fix frontmatter, restructure body
4. Categorize → Map to existing categories or propose new
5. Validate → Run audit script, update docs
6. Quality Gate → Check 5 gates, fix failures
7. Submit → PR with import summary and count changes
When to Use
Trigger phrases:
"ai skill integration guide"
"Integrating skills from an external GitHub repository"
"Bulk importing skills from a curated collection"
"Converting non-standard skill formats to 1ai-skills format"
Integrating skills from an external GitHub repository
Bulk importing skills from a curated collection
Converting non-standard skill formats to 1ai-skills format
Auditing an external repo for importable content
Validating skill quality before merge
How to Use
- Understand the requirement and existing codebase patterns
- Design the solution with error handling and testability in mind
- Implement incrementally with tests for each change
- Verify against expected outcomes (manual and automated)
- Document usage, edge cases, and integration points
- Review with team before merging to shared branches
When NOT to Use
- Task is about deployment, not development (use deploy skills)
- Task is about code review, not writing (use review skills)
- You need to understand existing code first (use research skills)
- Task is about testing only (use test skills)
- Requirements are unclear (clarify first)
- Task is trivially simple (single line fix)
Red Flags
- Skipping tests to ship faster: Untested code breaks in production when you least expect it
- No error handling in production code: Unhandled errors crash services and lose user data
- Hardcoded configuration values: Hardcoded values prevent environment switching and leak secrets
- Ignoring security implications: Missing input validation, auth bypasses, and injection vulnerabilities
- Over-engineering simple solutions: Premature abstraction adds complexity without proportional benefit
Verification
Anti-Rationalization Table
| Rationalization |
Reality |
| "Tests slow me down" |
Bugs slow you down 10x more. Tests are speed, not overhead. |
| "I will refactor later" |
Technical debt compounds. Refactor as you go. |
| "It works on my machine" |
If it is not in CI, it does not work. Ship proof, not claims. |
1---2name: ai-skill-integration-guide3description: Use when meta-skill for integrating external GitHub skill repos into4 1ai-skills. Covers discovery, deduplication, format conversion, category mapping,5 validation, and quality gates. Use when integrating external skill repos, bulk skill6 imports, skill format conversion.7domain: development8author: oyi779license: Apache-2.010subdomain: software-development11tags:12- meta13- integration14- skills15- github16- bulk-import17- format-conversion18- quality-gates19version: 1.0.020category: development21metadata:22 source: https://skillmd.com/skills/oyi77/ai-skill-integration-guide23---24252627## Overview2829Meta-skill that teaches agents how to integrate external skill repositories into the 1ai-skills library. Covers the full pipeline from discovery through validation, ensuring new skills are unique, properly formatted, correctly categorized, and quality-gated before merge.3031## Discovery3233Before importing anything, understand what the external repo offers.34351. Read the repo README for purpose, scope, and skill count362. Check if the repo uses SKILL.md files, AGENTS.md, or another structure373. List all skill files and extract their frontmatter (name, description, domain, tags)384. Identify the unique value — what does this repo offer that 1ai-skills does not already cover?3940```bash41# List all potential skill files in the external repo42find /path/to/external-repo -name "SKILL.md" -o -name "*.md" | head -504344# Extract frontmatter from each45for f in $(find /path/to/external-repo -name "SKILL.md"); do46 echo "=== $f ==="47 sed -n '/^---$/,/^---$/p' "$f"48done49```5051## Deduplication5253Always check for overlap before importing. Redundant skills degrade the library.54551. Grep existing SKILLS.json for similar skill names:5657```bash58grep -i "keyword" /home/openclaw/projects/1ai-skills/SKILLS.json59```60612. Grep existing skills for similar descriptions:6263```bash64grep -ri "description.*keyword" /home/openclaw/projects/1ai-skills/*/SKILL.md65```66673. Check the target category's current count and capacity684. For each candidate skill, document: overlaps found, unique value, import decision (import / skip / merge)6970## Format Conversion7172All 1ai-skills must follow the standard YAML frontmatter format.7374**Required frontmatter fields**:75```yaml76---77name: skill-name # kebab-case, unique across repo78description: What it does. Use when [trigger1], [trigger2]. # max ~200 chars79domain: category-name # must match an existing category directory80tags: 81- [tag182- tag283- tag3] # 3-8 relevant tags84---85```8687**Conversion checklist**:88- [ ] Name is kebab-case and unique (grep for conflicts)89- [ ] Description starts with what, ends with "Use when..." triggers90- [ ] Domain maps to an existing category directory91- [ ] Tags are lowercase, relevant, and not redundant with domain92- [ ] File is at `<category>/<skill-name>/SKILL.md`93- [ ] Body starts with `## Overview` after frontmatter94- [ ] No user-specific paths, tokens, or credentials hardcoded95- [ ] Content is self-contained — does not require external context to understand9697## Category Mapping9899Map external skills to the existing 18 categories:100101| Category | Focus |102|----------|-------|103| `automation/` | Bots, scrapers, pipelines, workflow automation |104| `agents/` | Agent architectures, autonomous systems |105| `content/` | Video, podcast, design, UI generation |106| `core/` | Self-improvement, memory, orchestration, infrastructure |107| `cybersecurity/` | Threat hunting, forensics, pen testing, SOC, compliance |108| `data/` | Data cleaning, visualization, pipelines, reporting |109| `development/` | TDD, debugging, code review, patterns, frameworks |110| `devops/` | Docker, K8s, CI/CD, cloud ops, GitOps |111| `financial/` | Finance analysis, investing, tax, accounting |112| `integrations/` | Platform integrations (GitHub, Discord, Notion, Slack) |113| `marketing/` | SEO, growth, email, social, affiliate |114| `mcp/` | MCP server skills |115| `meta/` | Self-improving meta-skills, skill management |116| `operations/` | Governance, KYC, project management, HR, legal |117| `productivity/` | Calendar, email, meetings, workspace tools |118| `research/` | Analysis, deep research, competitive intelligence |119| `sales/` | Lead gen, closing, B2B, CRM, influence |120| `trading/` | Crypto, DeFi, strategies, smart contracts |121122**If no category fits**: Propose a new category in the PR with justification. New categories need at least 3 skills to be viable.123124## Validation125126Run the full validation pipeline after import.127128```bash129# 1. Refresh the skill catalog130bash /home/openclaw/projects/1ai-skills/scripts/audit-skills.sh --write131132# 2. Verify counts match133bash /home/openclaw/projects/1ai-skills/scripts/audit-skills.sh134135# 3. Update documentation with new counts136# - README.md: skill count in header137# - llms.txt: category table138# - package.json: description field if count mentioned139# - AGENTS.md: category table140```141142## Quality Gates143144Every imported skill must pass these gates before merge:145146**Gate 1 — Self-Contained**: The skill is fully understandable without reading the source repo. No "see the README for details" — all details are in the SKILL.md.147148**Gate 2 — Actionable**: The skill provides concrete steps, commands, code examples, or decision frameworks. Not just a description of what something is.149150**Gate 3 — Unique Value**: No existing 1ai-skill covers the same ground. If there is overlap, the new skill must be clearly differentiated or merged into the existing one.151152**Gate 4 — Correct Format**: YAML frontmatter is valid, required fields present, naming conventions followed, category mapping is correct.153154**Gate 5 — No Leaks**: No hardcoded paths, API keys, user-specific config, or internal URLs. Safe for any user to install.155156## Process157158```1591. Discovery → Read repo, list skills, extract metadata1602. Dedup → Grep existing skills, document overlaps1613. Convert → Apply format, fix frontmatter, restructure body1624. Categorize → Map to existing categories or propose new1635. Validate → Run audit script, update docs1646. Quality Gate → Check 5 gates, fix failures1657. Submit → PR with import summary and count changes166```167168## When to Use169170**Trigger phrases:**171- "ai skill integration guide"172- "Integrating skills from an external GitHub repository"173- "Bulk importing skills from a curated collection"174- "Converting non-standard skill formats to 1ai-skills format"175176177- Integrating skills from an external GitHub repository178- Bulk importing skills from a curated collection179- Converting non-standard skill formats to 1ai-skills format180- Auditing an external repo for importable content181- Validating skill quality before merge182183## How to Use1841851. Understand the requirement and existing codebase patterns1862. Design the solution with error handling and testability in mind1873. Implement incrementally with tests for each change1884. Verify against expected outcomes (manual and automated)1895. Document usage, edge cases, and integration points1906. Review with team before merging to shared branches191192## When NOT to Use193194- Task is about deployment, not development (use deploy skills)195- Task is about code review, not writing (use review skills)196- You need to understand existing code first (use research skills)197- Task is about testing only (use test skills)198- Requirements are unclear (clarify first)199- Task is trivially simple (single line fix)200201202## Red Flags203204- **Skipping tests to ship faster**: Untested code breaks in production when you least expect it205- **No error handling in production code**: Unhandled errors crash services and lose user data206- **Hardcoded configuration values**: Hardcoded values prevent environment switching and leak secrets207- **Ignoring security implications**: Missing input validation, auth bypasses, and injection vulnerabilities208- **Over-engineering simple solutions**: Premature abstraction adds complexity without proportional benefit209210## Verification211212- [ ] Skill output matches expected behavior213214## Anti-Rationalization Table215216| Rationalization | Reality |217|---|---|218| "Tests slow me down" | Bugs slow you down 10x more. Tests are speed, not overhead. |219| "I will refactor later" | Technical debt compounds. Refactor as you go. |220| "It works on my machine" | If it is not in CI, it does not work. Ship proof, not claims. |