# Preflight

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-wujiajun4-preflight-preflight`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wujiajun4](https://agentstack.voostack.com/s/wujiajun4)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wujiajun4](https://github.com/wujiajun4)
- **Source:** https://github.com/wujiajun4/preflight

## Install

```sh
agentstack add skill-wujiajun4-preflight-preflight
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

| 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
```bash
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)

```bash
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:

```javascript
// 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:
10. Markdown links not broken
11. No trailing whitespace
12. All image paths resolve
13. 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](https://github.com/wujiajun4)
- **Source:** [wujiajun4/preflight](https://github.com/wujiajun4/preflight)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wujiajun4-preflight-preflight
- Seller: https://agentstack.voostack.com/s/wujiajun4
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.