skill-architect

Skill Architect

An enhanced skill architect wizard based on the official skill-creator, which uniformly takes over the former skill-lint review capability, has built-in compliance check rules, and supports two usage modes.

Backward-compatible alias: when users mention skill-lint , handle it according to this skill's review mode.

Usage Modes

Mode 1: Creation Mode

Use when creating a new skill, following this workflow:

1. Understand skill requirements (collect concrete examples)
2. Plan reusable resources (scripts/, references/, assets/)
3. Initialize the skill (create directory structure)
4. Edit the skill (implement resources + write SKILL.md)
5. Compliance check (built-in check rules)
6. Iterate (improve based on usage feedback)

Mode 2: Review Mode (formerly skill-lint)

Use when reviewing the compliance of an existing skill:

1. Specify the skill path to review
2. Scan the directory structure and files
3. Review item by item according to the checklist
4. Generate a structured review report

---

Mode 1: Creation Mode

Step 1: Understand skill requirements

Conditions for skipping this step: the skill's usage mode is already very clear.

Collect concrete usage examples:

• "What functionality should this skill support?"
• "Can you give some concrete usage scenarios?"
• "What would users say to trigger this skill?"

Completion criteria: clearly know the skill's functional boundaries and trigger scenarios.

---

Step 2: Plan reusable resources

Analyze each usage scenario to determine the required resources:

Resource type

Type	Directory	Purpose	When needed
Scripts	scripts/	Executable code	When the same code is rewritten repeatedly
References	references/	Detailed documentation	When schema/API documentation is needed
Assets	assets/	Output templates	When templates/icons/fonts are needed

Dependency planning

If the skill contains scripts, sort out dependency relationships in this step:

1. List all external dependencies: distinguish hard dependencies (cannot run without them) from optional dependencies (enhance functionality)
2. Plan a degradation strategy：
   • Hard dependencies: try/except + installation prompt + exit
   • Optional dependencies: try/except + feature flag + silent degradation
3. Prepare requirements.txt: include only hard dependencies
4. Plan where to explain in SKILL.md: place installation instructions nearby within the section of the feature that needs the dependency

Directory structure specification

Follow this structure when creating:

skill-name/
├── SKILL.md          # 必需 - 主文档
├── LICENSE.txt       # 推荐 - 许可证
├── references/       # 可选 - 参考文档
├── scripts/          # 可选 - 可执行脚本
└── assets/           # 可选 - 输出资源

Prohibited to create：

• README.md - duplicate with SKILL.md
• docs/ - should use references/
• test/ - Development files should not be in the release version
• __pycache__/ - Python caches should not be committed
• .env - Sensitive configuration should not be committed

---

Step 3: Initialize the skill

Create the skill directory and basic files:

1. Create the skill directory <skill-name>/
2. Create SKILL.md and add frontmatter
3. Create LICENSE.txt(recommended)
4. Create the required subdirectories (scripts/, references/, assets/）

---

Step 4: Edit the skill

4.1 Frontmatter specification

---
name: skill-name                    # 小写字母 + 连字符
description: 本技能应在用户需要...时使用。不要用于：...  # 第三人称 + 触发边界
version: "1.0.0"                   # 与 CHANGELOG 最新版本一致
license: MIT                       # 或 CC-BY-NC
author: 杨卫薪律师（微信ywxlaw）
homepage: https://github.com/cat-xierluo/legal-skills
---

description writing requirements：

• Use third person: "This skill should be used when..."
• Include trigger scenarios: clearly state when to use it
• Include negative trigger conditions: "Do not use for..." to explain the boundaries
• Keep the length within 1024 characters
• Do not add a "When to use" section in the body of SKILL.md

Publishing field requirements：

• version is a recommended field for public release; if present, it must match the latest version of CHANGELOG.md Consistent with the latest version
• CHANGELOG.md remains the source of the complete version history
• homepage is recommended to keep; when homepage already exists, source

4.2 SKILL.md content specification

Keep it concise：

• Avoid large blocks of code (>20 lines should be moved to scripts/）
• Use concise examples that show only key API calls
• Focus on the workflow, explaining "what to do" and "how to do it"

Progressive Disclosure：

• The core process goes in the body of SKILL.md
• Put detailed documentation in references/ Medium
• Reference references files in SKILL.md

4.3 Configuration file specification

Naming rules：

Type	Format	Whether to commit
Template file	*.example.*	Commit
Actual configuration	*	Ignored by .gitignore

Example:

• config.example.yaml → commit
• config.yaml → ignore
• .env.example → commit
• .env → ignore

4.4 Output mode specification

For skills that require consistent output, provide output format guidance.

Strict mode(API responses, data formats):

ALWAYS use this exact template structure:

# [Analysis Title]

## Executive summary
[One-paragraph overview]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

Flexible mode(analysis reports, creative content):

Here is a sensible default format, but use your best judgment:

# [Analysis Title]

## Executive summary
[Overview]

Adjust sections as needed for the specific context.

4.5 Workflow mode specification

Sequential workflow：

Filling a PDF form involves these steps:

1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Validate mapping (run validate_fields.py)
4. Fill the form (run fill_form.py)

Conditional workflow：

1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Step 1: ...
   - Step 2: ...

4.6 Skill collaboration specification

Loose coupling principle：

• Describe collaboration scenarios in natural language
• Explain what the skill "does" and "how it cooperates"
• Do not directly reference the internal script paths of other skills
• Do not import modules of other skills in code

Recommended approach：

## 与其他技能配合

下载的视频可以使用 FunASR 技能转录为带时间戳的 Markdown 文件。
两个技能独立运行，可根据需要灵活组合使用。

Approach to avoid：

## 与其他技能配合

转录时运行：
python ../../skills/funasr-transcribe/scripts/transcribe.py

4.7 Orchestrability design

For skills that may participate in complex workflow orchestration:

Input/output declaration：

## 输入/输出

### 输入
- 必需：`--input` 参数说明
- 可选：`--flag` 参数说明

### 输出
- 输出文件：`output/path.md` 说明
- 副作用：如创建目录、修改文件等

Single responsibility：

• The skill does only one thing
• Avoid mixing multiple tasks

Idempotency:：

• Multiple executions produce the same result
• No cumulative effect

---

Step 5: Compliance check

Before packaging, check each item according to the following checklist:

5.1 Directory structure

Check item	Status
SKILL.md exists	✅/❌
No README.md	✅/⚠️
No docs/ directory	✅/⚠️
No test/ directory	✅/⚠️
No pycache/	✅/❌
No .env file	✅/❌

5.2 Frontmatter

Check item	Status
name field exists and is correctly formatted	✅/❌
description field exists	✅/❌
description uses third person	✅/❌
description includes negative trigger conditions	✅/⚠️
description length ≤ 1024 characters (hard constraint)	✅/❌
description optimally ≤ 250 characters (information density recommendation)	✅/⚠️
version is consistent with the latest version in CHANGELOG	✅/⚠️
homepage/author/license recommended fields are complete	✅/⚠️
references/ subfiles have no frontmatter	✅/❌

5.3 SKILL.md line count

Check item	Status
SKILL.md line count ≤ 500 lines	✅/⚠️

5.4 Directory hierarchy

Check item	Status
references/ flat structure (one level)	✅/⚠️
scripts/ flat structure (one level)	✅/⚠️
assets/ flat structure (one level)	✅/⚠️

5.5 Documentation consistency

Check item	Status
Referenced script files exist	✅/❌
Referenced reference documents exist	✅/❌
Referenced asset files exist	✅/❌

5.6 Configuration files

Check item	Status
Template uses .example. naming	✅/⚠️
example field matches the code	✅/❌

5.7 Skill collaboration

Check item	Status
Does not directly reference other skill paths	✅/⚠️
Uses natural language to describe collaboration	✅/⚠️

5.8 Modular design

Check item	Status
Independent functions decoupled into separate scripts	✅/⚠️
Does not directly call internal scripts across skills	✅/⚠️

5.9 Security audit

Check item	Status
No hardcoded API keys	✅/❌
No dangerous deletion commands (rm -rf ~, etc.)	✅/❌
Deletion commands use a safe method	✅/⚠️

5.10 Dependency declaration and protection

Check item	Status
SKILL.md declares dependencies (distinguishes out-of-the-box vs install-required features)	✅/⚠️
Hard dependencies in scripts have try/except + installation prompt	✅/❌
Optional dependencies in scripts have try/except + fallback flag	✅/⚠️
requirements.txt contains only hard dependencies	✅/⚠️
Dependency installation instructions are placed nearby (within the corresponding feature section)	✅/⚠️

5.11 references/ subfile frontmatter restrictions

Check item	Status
references/*.md Does not carry frontmatter	✅/❌
Single source of metadata = SKILL.md frontmatter	✅/❌

Why：references/ is the detailed document expanded from SKILL.md references, and should not duplicate metadata; duplicated frontmatter creates a drift risk of "two descriptions / two names." Pre-scan command:

for f in references/*.md; do
  head -1 "$f" | grep -q "^---$" && echo "FRONTMATTER: $f"
done

5.12 Conceptual boundary between references/ naming and SKILL.md

Check item	Status
The filename reflects the "specific responsibility" (first_use / correction_patterns / boundaries）	✅/⚠️
Avoid generic words (overview / guide / intro）	✅/⚠️
Avoid naming that conceptually overlaps with SKILL.md (skill_overview / skill_intro）	✅/⚠️

Why：Generic words and naming that overlaps with SKILL.md will make readers mistakenly think "this is another main document." The naming should make it clear at a glance "what this document is for."

5.13 Public content cleanliness

Check item	Status
SKILL.md / references/ / CHANGELOG.md / config/.example. / DECISIONS.md / TASKS.md does not contain other skill names	✅/❌
Does not contain private workflow project names / in-house platform names	✅/❌
Use generic descriptions when upstream/downstream collaboration is involved	✅/❌

Counterexample：

• "Shares the dictionary format with course-generator" → "The same dictionary file can be read as needed with other downstream processing tasks"
• "Transcript produced by funasr" → "Output from a local transcription engine / cloud ASR"

Why：A public repository should carry only the "workflow itself"; once the dependencies of a private workflow (other skills / in-house platforms) enter the repository, they form "public coupling," and reviewers cannot determine whether they are real dependencies or historical leftovers.

Determination command：

# 找出所有可能的项目 / skill 名
grep -nE "course[- ]?generator|funasr|tingwu|听悟|xx-skill|其他 skill" SKILL.md references/*.md

5.14 Git tracking status

Check item	Status
SKILL.md / CHANGELOG.md / LICENSE.txt are git-tracked	✅/❌
config/.example. is git-tracked	✅/❌
references/*.md are git-tracked	✅/❌
Real configuration (config/*.yaml) is covered by .gitignore	✅/❌
Private archives (archive/, DECISIONS.md, TASKS.md) are covered by .gitignore	✅/❌
The entire skill directory is not git status in ?? status	✅/❌

Why：When the skill has been registered in .claude-plugin/marketplace.json and README but git ls-files returns empty, external users will see no files when they clone the repository—this is the state of "looks published but actually does not exist."

Determination command：

# 必跑：验证已跟踪文件
git ls-files skills/<skill-name>/ | head -20
# 必跑：验证 .gitignore 覆盖
git check-ignore -v skills/<skill-name>/config/<real-config>.yaml
# 严重警告：整个 skill 目录未跟踪
git status --porcelain skills/<skill-name>/ | grep '^??'

5.15 CHANGELOG historical consistency

Check item	Status
The v1.0.0 section describes only the capabilities of "v1.0.0 as it is now"	✅/⚠️
Capability increments of later versions are added in the corresponding version sections	✅/⚠️
Each version section does not include capabilities that are "not yet implemented"	✅/⚠️

Counterexample：The v1.0.0 section already describes capabilities such as "source file directory mirroring / STABLE.md markers / required checklist" that were only complete in v1.0.6—readers cannot tell from the v1.0.0 section whether "the v1.0.0 I installed really has these capabilities."

Why：CHANGELOG is a version archaeology document, and each version section should faithfully reflect "the capabilities at the time that version was released," with later increments added in new version sections.

5.16 Internal consistency of archive/

Check item	Status
When the number of archive/ subdirectories is ≥ 5, STABLE.md / DECISIONS.md records the retention policy	✅/⚠️
In STABLE.md, the [DEC-XXX] The numbering is consistent with the actual entries in DECISIONS.md	✅/⚠️
The cumulative data in STABLE.md (description lines + table rows) is self-consistent	✅/⚠️

Why: Although archive/ has been isolated by .gitignore, as the skill-internal "carrier of proofreading quality," its internal consistency affects the trust level of subsequent agents / downstream skills when reading it.

5.17 description content boundaries (only write three things)

Check item	Status
description contains only the three things "function / trigger / non-trigger"	✅/❌
Does not include archiving / output location / write strategy	✅/❌
Does not include internal steps / toggle states / default behavior	✅/❌
Does not include artifact structure / side effects / dual-write strategy	✅/❌

Content definitions of the three things：

Paragraph	Question it should answer	Example
Function	What this skill is / does	"Transcript error correction and light optimization"
Trigger	In what scenarios to use / what the user says will trigger it	"This skill should be used when the user needs..."
Non-trigger	In what scenarios it cannot be used / avoid false triggers	"Do not use for: rewriting, summarizing, cutting, changing facts"

Counterexamples(that should not appear in the description):

Counterexample content	Why it should not appear
"Results are archived in archive/ and a copy is synchronized in the source directory"	Output strategy is an operational detail; move it to SKILL.md §5 Output phase
"Original files remain untouched"	Internal behavior constraint; move it to SKILL.md workflow principles
"(enabled by default) / (disabled by default)"	Toggle states are configuration instructions; move them to the SKILL.md Phase description
"Includes basic whitespace cleanup and spoken-word reduction"	Internal step list; move it to the SKILL.md Overview table
"Optionally merge consecutive utterances by the same speaker"	Optional feature list; move it to the SKILL.md Overview table

Why: description is the trigger's "matching fingerprint"—the Claude model looks at description first during routing decisions; the more focused the trigger (including "what it does / when to use / when not to use"), the more accurate the routing. Archiving strategy, default behavior, and internal steps belong to "how it works after being triggered" and are unrelated to trigger judgment.

Determination command：

# 找出可能越界的"运作细节"关键词
grep -nE "归档|原始文件|默认开启|默认关闭|默认无损|同步|双写|在.*目录|在.*目录.*副本|输出到" SKILL.md | head -5

Manually compare against the description text to confirm these keywords do not appear in the frontmatter description field.

Counterexample case：

• transcription-corrector v1.0.7 description (before correction): "Transcript error correction and light optimization: correct ASR homophones / English proper-noun drift (names, products, terminology) according to the user dictionary, with basic whitespace cleanup and spoken-word reduction (enabled by default), optional merging of consecutive utterances by the same speaker / punctuation normalization; original files remain untouched, results are archived in archive/ and a copy is synchronized in the source directory." → contains archiving strategy / default behavior / internal steps, cleaned up in the v1.0.7 corrected version.

Issue severity：

Level	Description	Handling
❌ Severe	Blocks normal use of the skill	Must fix
⚠️ Warning	Affects maintainability	Recommended fix

---

Step 6: Iterate

Improve the skill based on actual usage feedback:

1. Use the skill to handle real tasks
2. Identify difficulties or efficiency issues
3. Update SKILL.md or related resources

---

Mode 2: Review Mode (formerly skill-lint)

Review the compliance of existing skills and generate a structured review report.

Review process

1. Specify the target - Provide the path of the skill to review
2. Scan files - List all files in the skill directory
3. Check item by item - Review according to the checklist (using the same rules as Step 5)
4. Generate report - Output structured review results

Review report format

# [skill-name] 格式审查报告

**审查时间**: YYYY-MM-DD HH:MM
**技能路径**: /path/to/skill

## 审查摘要

| 检查项 | 状态 | 问题数 |
|--------|------|--------|
| 目录结构 | ✅/⚠️/❌ | N |
| Frontmatter | ✅/⚠️/❌ | N |
| SKILL.md 行数 | ✅/⚠️ | N |
| 目录层级 | ✅/⚠️ | N |
| 文档一致性 | ✅/⚠️/❌ | N |
| 配置文件 | ✅/⚠️/❌ | N |
| 技能协作 | ✅/⚠️/❌ | N |
| 模块化设计 | ✅/⚠️ | N |
| 安全审计 | ✅/❌ | N |

## 详细问题

### ❌ 严重问题（必须修复）

1. **[问题标题]**
   - 位置: `文件路径:行号`
   - 规范: 违反的规范条款
   - 建议: 修复建议

### ⚠️ 建议优化

1. **[问题标题]**
   - 位置: `文件路径`
   - 建议: 优化建议

## 审查完成

- 总问题数: N
- 严重问题: N
- 建议优化: N

Review execution method

1. Use Glob to list all files in the skill directory
2. Use Read to read SKILL.md and key files
3. Review item by item according to the Step 5 checklist
4. Generate a structured review report

---

Specification reference

For detailed specification standards, see references/skill-standards.md