From 58cc9d8c9feed122920f526247cd232a2be39642 Mon Sep 17 00:00:00 2001 From: CWF Date: Thu, 23 Apr 2026 11:55:37 +0800 Subject: [PATCH] chore: initialize .github/maintainer/ state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bootstraps the per-repo state used by the open-source-maintainer skill so future triage runs have a persistent home for decisions, patterns, contributor notes, and run ledgers. Seeds: - config.json with schemaVersion: 1 and noMergeExternalPRs: true - context.md with current vision, priorities, areas, tone, and out-of-scope - decisions.md with the first entry (PR:1 — full skill bundle install) - patterns.md with the partial-download anti-pattern that motivated PR:1 - standing-rules.md with stale policy, area labels, and security-first defaults - Empty contributors.md, runs.md, state.json, and notes/work/index/ dirs No user-facing behavior changes. Co-Authored-By: Claude Opus 4.7 --- .github/maintainer/config.json | 6 ++++ .github/maintainer/context.md | 50 ++++++++++++++++++++++++++++ .github/maintainer/contributors.md | 13 ++++++++ .github/maintainer/decisions.md | 10 ++++++ .github/maintainer/index/.gitkeep | 0 .github/maintainer/notes/.gitkeep | 0 .github/maintainer/patterns.md | 21 ++++++++++++ .github/maintainer/runs.md | 7 ++++ .github/maintainer/standing-rules.md | 34 +++++++++++++++++++ .github/maintainer/state.json | 7 ++++ .github/maintainer/work/.gitkeep | 0 11 files changed, 148 insertions(+) create mode 100644 .github/maintainer/config.json create mode 100644 .github/maintainer/context.md create mode 100644 .github/maintainer/contributors.md create mode 100644 .github/maintainer/decisions.md create mode 100644 .github/maintainer/index/.gitkeep create mode 100644 .github/maintainer/notes/.gitkeep create mode 100644 .github/maintainer/patterns.md create mode 100644 .github/maintainer/runs.md create mode 100644 .github/maintainer/standing-rules.md create mode 100644 .github/maintainer/state.json create mode 100644 .github/maintainer/work/.gitkeep diff --git a/.github/maintainer/config.json b/.github/maintainer/config.json new file mode 100644 index 0000000..3438a8f --- /dev/null +++ b/.github/maintainer/config.json @@ -0,0 +1,6 @@ +{ + "schemaVersion": 1, + "reportsDir": "reports", + "stateFile": ".github/maintainer/state.json", + "noMergeExternalPRs": true +} diff --git a/.github/maintainer/context.md b/.github/maintainer/context.md new file mode 100644 index 0000000..de107da --- /dev/null +++ b/.github/maintainer/context.md @@ -0,0 +1,50 @@ +# Project Context + +## Vision + +`skill-fetch` is a cross-platform skill discovery and installation tool for AI coding agents. It searches 9 registries in parallel (SkillsMP, GitHub, Anthropic Skills, ClawSkillHub, skills.sh, PolySkill, SkillHub, Skills Directory), scores results, runs a 6-category security scan, and installs skills into the correct per-agent directory. Target agents: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Amp. + +## Current Priorities + +1. **Install reliability** — installed skills must be complete and functional (full bundle, not partial). Integrity verifiable via SHA-256. +2. **Security hygiene** — maintain and improve the 6-category scan (especially prompt-injection coverage) as new attack patterns emerge. +3. **Cross-platform parity** — ensure install paths, tool-name mappings, and fallback strategies stay correct as agents evolve. +4. **Onboarding friction** — keep Quick Start ≤3 steps; detect and recover from missing API keys / missing MCP server automatically. + +## Success Metrics + +- Zero broken installs (skill downloaded but missing files it references) +- Zero silent "too few results" (always query all 9 sources; report per-source status) +- Every public skill directory layout (including `assets/`, `templates/`, `prompts/`, `data/`, `examples/`, `scripts/*.{sh,py,js,ts}`) installs correctly +- API key configuration works without manual JSON editing (`/fetch-skill-config`) + +## Areas + +| Area | Status | Notes | +|------|--------|-------| +| `skills/skill-fetch/SKILL.md` | Stable, high-scrutiny | Entry point; hook-facing behavior. Changes need care. | +| `skills/skill-fetch/references/*.md` | Active | Progressive-disclosure references. Keep each file focused. | +| `skills/skill-fetch/scripts/*.sh` | Stable | Must pass ShellCheck `--severity=warning`. | +| `install.sh` / `install.py` | Stable | Bootstrap for non-plugin installs. Smoke-tested in CI. | +| `commands/*.md` | Stable | Thin command wrappers that delegate to the skill. | +| `.claude-plugin/` | Stable | Plugin manifest for Claude Code marketplace. | +| `.github/workflows/ci.yml` | Stable | ShellCheck + frontmatter + installer smoke test. | + +## Contribution Guidelines + +- Never hardcode subdirectory names or file extensions in install logic — skills bundle arbitrary content. +- Never hardcode source-specific lookups into SKILL.md when a reference file will do; keep SKILL.md thin (progressive disclosure). +- Every new shell script must pass ShellCheck at `--severity=warning`. +- API keys must never appear on command lines — always via bundled script + config file. +- User-facing interactions stay plain-text (no `AskUserQuestion`); show 5 results per page with `c` to continue. +- When adding a new source, fire it in parallel with all others — never gate later sources on earlier results. + +## Tone + +Technical, concise, actionable. Prefer terse PR descriptions with a clear test plan over long narratives. Use concrete numbers when possible (file counts, query counts, hit rates). + +## Out of Scope + +- Merging external PRs (intent is extracted; the maintainer agent implements the fix). +- Long-running background services, MCP server hosting, or API proxying. This repo ships a client/installer, not a registry. +- Skill authoring helpers or skill-writing templates — covered by separate skills. diff --git a/.github/maintainer/contributors.md b/.github/maintainer/contributors.md new file mode 100644 index 0000000..9b9cfb2 --- /dev/null +++ b/.github/maintainer/contributors.md @@ -0,0 +1,13 @@ +# Contributor Notes + +This file tracks the humans contributing to `skill-fetch`. The maintainer agent adds notes after meaningful interactions (issues/PRs/reviews) so future triage can adapt tone and guidance. + +## Active Contributors + +### @girofu (maintainer) +- **Role:** Project owner / primary maintainer +- **Notes:** Works bilingually (繁體中文 / English). Prefers terse, evidence-backed responses. + +## Former Contributors + +_(none yet)_ diff --git a/.github/maintainer/decisions.md b/.github/maintainer/decisions.md new file mode 100644 index 0000000..394dbf6 --- /dev/null +++ b/.github/maintainer/decisions.md @@ -0,0 +1,10 @@ +# Decision Log + +Decisions recorded here are the project-level calls: scope, policy, architecture, closures. One line per entry minimum; add rationale when the "why" is non-obvious. + +## 2026-04 + +### [PR:1] Opened — Download full skill bundle, not just SKILL.md +**Date:** 2026-04-23 +**Decision:** Replaced hardcoded `SKILL.md` + `references/*.md` + `scripts/*.sh` install logic with full git-tree enumeration via `scripts/fetch-skill-bundle.sh`. +**Reasoning:** Any skill that ships `.py`/`.js` scripts, or uses subdirs beyond `references/`/`scripts/` (e.g., `assets/`, `templates/`, `prompts/`, `data/`), was silently broken on install. End-to-end test against `anthropics/skills/skills/pdf` confirmed: old flow → 1 file, new flow → 12 files with correct subtree. Treats the skill as its directory, not as `SKILL.md`. diff --git a/.github/maintainer/index/.gitkeep b/.github/maintainer/index/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.github/maintainer/notes/.gitkeep b/.github/maintainer/notes/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.github/maintainer/patterns.md b/.github/maintainer/patterns.md new file mode 100644 index 0000000..6cff1cc --- /dev/null +++ b/.github/maintainer/patterns.md @@ -0,0 +1,21 @@ +# Observed Patterns + +Patterns the maintainer agent has learned while operating the repo. Use these to pattern-match new issues faster and to preempt recurring mistakes. + +## Recurring Issues + +### Partial skill downloads (install the directory, not the file) +- **First observed:** 2026-04-23 (internal review → [PR:1]) +- **Cause:** Install logic hardcoded `SKILL.md` + `references/*.md` + `scripts/*.sh`. Skills that ship `.py` scripts, `assets/`, `templates/`, etc. were installed with missing files. +- **Resolution:** Full git-tree enumeration via `scripts/fetch-skill-bundle.sh` (PR:1). +- **Prevention:** Never hardcode subdir names or extensions in install/scan logic. Walk the tree. + +## Codebase Patterns + +- SKILL.md is the public contract; references/ files are progressive disclosure. Keep SKILL.md lean; push detail down into reference files. +- Every shell script must pass ShellCheck `--severity=warning`. CI enforces this. +- API keys live in `~/.claude/skills/.fetch-config.json` and are loaded by bundled scripts — never on command lines. + +## Contributor Patterns + +_(none yet — file grows as PRs/issues come in)_ diff --git a/.github/maintainer/runs.md b/.github/maintainer/runs.md new file mode 100644 index 0000000..dc5ab73 --- /dev/null +++ b/.github/maintainer/runs.md @@ -0,0 +1,7 @@ +# Run Ledger + +Append one entry per triage run. Keep entries terse; link to the full report dir for detail. + +| Date | Report | Issues/PRs scanned | Notes | +|------|--------|---------------------|-------| +| _(first run pending)_ | — | — | State initialized 2026-04-23 on `girofu/maintainer-init`; no open issues/PRs yet. | diff --git a/.github/maintainer/standing-rules.md b/.github/maintainer/standing-rules.md new file mode 100644 index 0000000..9575afe --- /dev/null +++ b/.github/maintainer/standing-rules.md @@ -0,0 +1,34 @@ +# Standing Rules + +Automation policies the maintainer agent applies by default. Human approval is still required for any public-facing action; these rules describe the agent's *recommendations*, not auto-executes. + +## Stale Policy + +| Condition | Days | Recommended Action | +|-----------|------|--------------------| +| Issue waiting on reporter | 30 | Comment asking for update | +| Issue waiting on reporter | 60 | Close as stale | +| PR waiting on author | 30 | Close as stale | + +## Auto-Label Suggestions + +| Condition | Label | +|-----------|-------| +| PR or issue touches `skills/skill-fetch/SKILL.md` | `area:skill-core` | +| PR or issue touches `skills/skill-fetch/scripts/` | `area:scripts` | +| PR or issue touches `install.sh` / `install.py` | `area:installer` | +| PR or issue touches `.claude-plugin/` | `area:plugin` | +| Issue mentions install failure, 404, missing file | `type:install-bug` | +| Issue mentions security, prompt injection, RCE | `priority:security` | +| First-time contributor | `first-contribution` | + +## External PR Handling + +- **Never merge external PRs.** Extract intent via `references/intent-extraction.md`, implement the fix in a maintainer-authored PR, and close the original with a crediting comment. +- When the original PR has useful test cases or reproductions, reuse them (with attribution) in the maintainer PR. + +## Security-First Defaults + +- Any new source/script that touches user API keys must read from `~/.claude/skills/.fetch-config.json`, never from argv. +- Any install-path change must preserve the directory layout of the source skill; adding implicit filtering is forbidden. +- Any change to the 6-category security scan must include a positive test case (a fixture that should trip the new rule). diff --git a/.github/maintainer/state.json b/.github/maintainer/state.json new file mode 100644 index 0000000..a8806d5 --- /dev/null +++ b/.github/maintainer/state.json @@ -0,0 +1,7 @@ +{ + "schemaVersion": 1, + "lastRunAt": null, + "lastReportDir": null, + "issueHashes": {}, + "prHashes": {} +} diff --git a/.github/maintainer/work/.gitkeep b/.github/maintainer/work/.gitkeep new file mode 100644 index 0000000..e69de29