Preflight

| Mode | Checks | Use when | |------|--------|----------| | preflight | 6 content checks | Every release | | preflight --distribute | 6 content + 3 distribution | Publishing a skill/product | | preflight --strict | 10 content checks | Polishing pass | | preflight --fix | Auto-fix common issues | Quick cleanup |

Preflight — "Don't ship half-baked. Don't ship invisible."

The Problem (v2.0 insight)

v1.0 caught content bugs — placeholders, missing LICENSE, private tools. But after pushing 4 products and getting zero organic discovery, the real gap became clear:

Content quality ≠ distribution quality.

You can have a perfect README, but if your repo has no topics, it's invisible to GitHub search. If it's not on skills.sh, the 67-platform skill ecosystem can't find it. If the install command appears once buried in the README, nobody knows how to use it.

Modes

| Mode | Checks | When | |------|--------|------| | Default (preflight) | #1–6 Content | Every release | | Distribute (preflight --distribute) | #1–6 Content + #7–9 Distribution | Publishing a skill or public product | | Strict (preflight --strict) | #1–10 All | Final polish pass | | Fix (preflight --fix) | #1–6 + auto-patch | Quick cleanup |

The Nine Checks

Content Checks (#1–6)

| # | Check | Why it matters | |---|-------|---------------| | 1 | Placeholders | YOUR_USERNAME, TODO, FIXME in published code is embarrassing | | 2 | LICENSE file | Declaring MIT without a LICENSE file = legally ambiguous | | 3 | No private tool refs | ctx_fetch_and_index, ctx_execute only work on your machine | | 4 | .gitignore exists | Without it, .DS_Store and logs leak into the repo | | 5 | Bilingual README | English-only misses half your audience; Chinese-only misses the other half | | 6 | File structure | Missing README? Missing SKILL.md? Ship the full package |

Distribution Checks (#7–9) — only in --distribute mode

| # | Check | Why it matters | How to verify | |---|-------|---------------|---------------| | 7 | GitHub Topics | Empty topics = invisible to GitHub search | gh api repos/{owner}/{repo}/topics → must have ≥5 | | 8 | skills.sh discoverable | This is the 67-platform skill marketplace | Check: repo has skill + agent-skills topics AND a SKILL.md with user-invocable: true | | 9 | Install command visibility | Users need to see the command 3+ times to act | Count npx skills add or git clone occurrences in README.md → should appear ≥3 times |

Pipeline

Step 1: Detect Project Type

ls README.md 2>/dev/null && echo "HAS_README" || echo "NO_README"
ls SKILL.md 2>/dev/null && echo "HAS_SKILL" || echo "NO_SKILL"
ls package.json 2>/dev/null && echo "NPM" || true
# Extract repo name from git remote for API checks
git remote get-url origin 2>/dev/null | sed 's/.*github.com[:\/]\(.*\)\.git/\1/'

Step 2: Run Content Checks (#1–6)

echo "=== CHECK 1: PLACEHOLDERS ==="
PLACEHOLDER_FILES=$(grep -rn 'YOUR_USERNAME\|>>\|FIXME\|XXX_REPLACE_ME' \
  README.md SKILL.md LICENSE CHANGELOG.md package.json 2>/dev/null)
if [ -z "$PLACEHOLDER_FILES" ]; then
  echo "PASS: No placeholder strings found"
else
  echo "FAIL: Placeholders found:"
  echo "$PLACEHOLDER_FILES"
fi

echo "=== CHECK 2: LICENSE ==="
if ls LICENSE* 1>/dev/null 2>&1; then
  echo "PASS: LICENSE file exists"
else
  echo "FAIL: No LICENSE file found"
fi

echo "=== CHECK 3: PRIVATE TOOL REFS ==="
PRIV_TOOLS=$(grep -rn 'ctx_fetch_and_index\|ctx_execute_file\|ctx_batch_execute\|ghost_os\|mcp__ghost-os' \
  SKILL.md README.md 2>/dev/null)
if [ -z "$PRIV_TOOLS" ]; then
  echo "PASS: No private tool references found"
else
  echo "FAIL: Private tool references found:"
  echo "$PRIV_TOOLS"
fi

echo "=== CHECK 4: GITIGNORE ==="
if ls .gitignore 1>/dev/null 2>&1; then
  HAS_DSSTORE=$(grep -c '\.DS_Store' .gitignore 2>/dev/null || echo 0)
  echo "PASS: .gitignore exists (covers .DS_Store: $([ "$HAS_DSSTORE" -gt 0 ] && echo 'yes' || echo 'no'))"
else
  echo "FAIL: No .gitignore file found"
fi

echo "=== CHECK 5: BILINGUAL ==="
README_LINES=$(wc -l /dev/null || echo 0)
if [ "$README_LINES" -gt 0 ]; then
  HAS_EN=$(grep -c '[A-Za-z]\{20,\}' README.md 2>/dev/null || echo 0)
  HAS_CN=$(grep -c '[\x{4e00}-\x{9fff}]\{4,\}' README.md 2>/dev/null || echo 0)
  echo "README: $README_LINES lines, EN segments: $HAS_EN, CN segments: $HAS_CN"
  if [ "$HAS_EN" -gt 0 ] && [ "$HAS_CN" -gt 0 ]; then
    echo "PASS: README has both English and Chinese content"
  elif [ "$HAS_EN" -gt 0 ]; then
    echo "WARN: README is English-only"
  elif [ "$HAS_CN" -gt 0 ]; then
    echo "WARN: README is Chinese-only"
  fi
else
  echo "SKIP: No README.md found"
fi

echo "=== CHECK 6: FILE STRUCTURE ==="
FILES_OK=true
for f in README.md .gitignore; do
  if [ ! -f "$f" ]; then echo "MISSING: $f"; FILES_OK=false; fi
done
if [ -f "SKILL.md" ]; then
  for f in SKILL.md LICENSE assets/; do
    if [ ! -e "$f" ]; then echo "MISSING (skill): $f"; FILES_OK=false; fi
  done
fi
$FILES_OK && echo "PASS: File structure complete" || echo "FAIL: Missing files detected"

Step 3: Run Distribution Checks (#7–9) — only in --distribute mode

These checks need network access. Use ctx_execute (Node.js) to query GitHub API:

// CHECK 7: GitHub Topics
const resp = await fetch('https://api.github.com/repos/{owner}/{repo}/topics', {
  headers: { 'Accept': 'application/vnd.github+json', 'User-Agent': 'preflight' }
});
const data = await resp.json();
const topics = data.names || [];
if (topics.length >= 5) {
  console.log('PASS: ' + topics.length + ' GitHub topics set: ' + topics.join(', '));
} else if (topics.length > 0) {
  console.log('WARN: Only ' + topics.length + ' topics. Recommend ≥5. Missing: claude-code, skill, agent-skills');
} else {
  console.log('FAIL: ZERO GitHub topics. Repo is invisible to search.');
  console.log('→ Fix: Add topics at github.com/{owner}/{repo}/settings (top of page)');
  console.log('→ Recommended: claude-code, skill, agent-skills, developer-tools, {domain-specific}');
}

// CHECK 8: skills.sh discoverable
// Read SKILL.md frontmatter
const skillContent = require('fs').readFileSync('SKILL.md', 'utf8');
const isUserInvocable = skillContent.includes('user-invocable: true');
const hasSkillTag = topics.some(t => t === 'skill' || t === 'agent-skills');
if (hasSkillTag && isUserInvocable) {
  console.log('PASS: skills.sh will auto-index this skill (topics + SKILL.md ok)');
} else {
  console.log('WARN: May not be auto-discovered by skills.sh');
  if (!hasSkillTag) console.log('→ Add topic: skill or agent-skills');
  if (!isUserInvocable) console.log('→ Set user-invocable: true in SKILL.md frontmatter');
}

// CHECK 9: Install command visibility
const readme = require('fs').readFileSync('README.md', 'utf8');
const installCount = (readme.match(/npx skills add/g) || []).length +
                     (readme.match(/git clone.*github\.com\/{owner}\/{repo}/g) || []).length;
if (installCount >= 3) {
  console.log('PASS: Install command appears ' + installCount + ' times in README');
} else if (installCount > 0) {
  console.log('WARN: Install command only appears ' + installCount + ' times. Recommend ≥3.');
  console.log('→ Add it: below header, in Install section, and in footer');
} else {
  console.log('FAIL: No install command found in README');
  console.log('→ Add: npx skills add {owner}/{repo} -g');
}

Step 4: Output the Report Card

## Preflight Report — {project_name}

### Content (#1–6)
| # | Check | Result | Detail |
|---|-------|--------|--------|
| 1 | Placeholders | ✅ PASS | No YOUR_USERNAME/TODO/FIXME found |
| 2 | LICENSE | ✅ PASS | MIT license present |
| 3 | Private tools | ✅ PASS | Clean |
| 4 | .gitignore | ✅ PASS | Exists, covers .DS_Store |
| 5 | Bilingual | ⚠️ WARN | English-only README |
| 6 | File structure | ✅ PASS | README+SKILL+LICENSE+gitignore+assets |

### Distribution (#7–9) [--distribute mode]
| # | Check | Result | Detail |
|---|-------|--------|--------|
| 7 | GitHub Topics | ❌ FAIL | 0 topics set. Repo invisible to GitHub search. |
| 8 | skills.sh | ⚠️ WARN | Missing 'skill' topic. Add it for auto-indexing. |
| 9 | Install visibility | ⚠️ WARN | Install command appears only 1 time. Add 2+ more. |

**Verdict: Content 5/6, Distribution 0/3. Fix #7 before shipping.**

Step 5 (Optional): Auto-Fix Mode (--fix)

• Placeholders → replace YOUR_USERNAME with detected GitHub user
• LICENSE → generate MIT template with current year
• .gitignore → create with .DS_Store, *.log, node_modules/
• Private tool refs → warn but don't auto-replace (needs human judgment)
• NEW: README install command → if missing from header, inject npx skills add ... after badge row

Strict Mode (--strict)

Adds #10–13:

1. Markdown links not broken
2. No trailing whitespace
3. All image paths resolve
4. CHANGELOG.md has entry for current version

Rules

• Never modifies files unless --fix is explicitly passed.
• Distribution checks need network. They call GitHub API. In sandbox, use ctx_execute Node.js.
• Distribution checks are warnings by default in preflight, FAILs in --distribute.
• The report card is the product. Table + verdict, no walls of text.
• Failures are specific. "0 GitHub topics" not "distribution issues."

v2.0 Changelog

| What | Why | |------|-----| | --distribute mode | Content quality ≠ distribution quality. 4 shipped products got 0 organic discovery. | | Check #7: GitHub Topics | Empty topics = invisible to GitHub search. Caught on 2026-06-06 launch. | | Check #8: skills.sh discoverable | 67-platform ecosystem can't find skills without skill topic + SKILL.md. | | Check #9: Install visibility | Users need 3+ install command sightings to act. Hot repos have 24-26. | | Progressive disclosure | L1 100-token mode summary for fast routing. | | Structured triggers | Keywords + events for auto-invoke. |

v2.0.1 (2026-06-07)

| What | Why | |------|-----| | FIX: Move argument-hint to dedicated frontmatter field | Was crammed in description after 126 SKILL.md bulk rewrite — same regression that hit brain-sync and tool-eval | | FIX: Add CJK trigger inline in description | Standard pattern from skill-lens v1.1.0 | | NEW: Add triggers.phases block | Maps 9 checks to execution phases (placeholders, license, private-tools, gitignore, bilingual, file-structure, github-topics, skills-sh, install-visibility) | | NEW: v2.0.1 changelog section | Transparency for patch-level changes | | FIX: git remote URL cleaned | Was leaking old PAT ghp_TVHOf*** (旧 token 已撤销，仅前 10 字符保留供识别) |

---

Security Note

This skill is an instruction-only skill (no scripts). For related skills with scripts, see lens.cjs in skill-lens and the secure-push pattern documentation. Key principles:

• Never write full PAT tokens in documentation — use ghp_TVHOf*** masked form
• Always run git remote set-url after push to clean embedded old PATs
• GitHub secret scanner watches SKILL.md content — not just commit messages

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wujiajun4
• Source: wujiajun4/preflight
• License: MIT

Install and usage instructions live in the source repository linked above.