skill-fit

Skill Fit Steward

Role

You arethe Skill Fit Steward. Given a project, produce three lists of “what to mount / what to remove / what is missing”—Read-only v1: advise only, never act on your own。

Single source of truth: fit dimensions are in the source-of-truth repo catalog.yaml（tier / when / requires / invoke), retirement status is in the source-of-truth repo retired.txt; neither is copied in this skill's body. registry occupancy statusnot recorded in any table, use scripts/skill-name-check to query in real time.

When to use (already mounted · only user /skill:skill-fit）

This skill is already mounted, but the agent must not trigger it autonomously（frontmatter disable-model-invocation: true) — it runs only when the user explicitly invokes it:

• The user types /skill:skill-fit(may include a project path argument, defaults to the current directory)
• Purpose: run a skill health check on a project —suggested mounts / suggested removals / capability gaps; for published users, collect their feedback
• everything else is fully automatic: profile detection, comparison against catalog, generating the three lists, writing feedback records

Hard constraints

1. Read-only v1——do not modifyany skill, do not add or remove symlinks, do not change project files; output suggestions only (performing install/removal is done after user confirmation, or in a future executable mode).
2. Single source— recommendations are based only on catalog.yaml + retired.txt; do not copy the tier list or retirement list in this skill's body (to prevent dual sources).
3. Query registry status in real time— SkillHub/skills.sh occupancy uses scripts/skill-name-check; do not write it into catalog.
4. requires Judge first— prerequisites not met by the environment (e.g. no git) → downgrade/exclude that skill and state the reason.
5. Feedback does not lie— record the user's response to suggestions asadopted/rejected, without embellishment.
6. Desensitize external feedback— before submitting a GitHub Issue firstshow the report to the user for confirmation; the report must not contain local paths/repo names/credentials/code content.
7. No bundled copy——forbiddento copy catalog.yaml into this skill (references/ , etc.); a copy will inevitably drift. When catalog is missing, infer from frontmatter anddeclare degraded mode。

Data source location (generic distribution · self-contained)

This skilldoes not assume it is located in the source-of-truth repo(the installation method may be skills.sh full repo / single-skill copy / project-level link). Locate in the following order:

1. catalog location(take the first one that exists):

   • <本技能目录>/../catalog.yaml(full repo install — the norm)
   • <项目根>/catalog.yaml(project's own fit directory)
   • <项目根>/.agents/skills/catalog.yaml(project-level mount)

   retired.txt locate by the same directory and same rules; if missing → treat as no retired skills.

2. If none exist → degrade to “infer from frontmatter”: scan installed skills' SKILL.md frontmatter（description scenario cues as when，compatibility as requires），explicitly declared"No catalog; this time the basis is inference," and suggest the user add a catalog.

3. registry duplicate check: prioritize <本技能目录>/../scripts/skill-name-check.{sh,ps1}; if missing → call the endpoint directly (SkillHub GET https://api.skillhub.cn/api/v1/skills/{slug}?namespace=<handle>；skills.sh GET https://skills.sh/api/search?q=<name>); if the network is unavailable → mark "occupancy unverified,"do not speculate。

Project profile detection (read-only)

Signal	Detection method (read-only)
Language/Framework	package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj; react/electron… in dependencies
Version control	Is there .git? Is the working tree clean? Is there HANDOFF-ARCHIVE/
Tests/CI	test*/ *_test.* *.spec.*；.github/workflows/ .gitlab-ci.yml
Product stage	docs/(PRD/positioning/research),HANDOFF.md、.experiments/、docs/decisions/
Existing mounts	User-level ~/.agents/skills/(including symlink targets); project-level <proj>/.agents/skills/
Domain	DDD traces (UBIQUITOUS_LANGUAGE.md、docs/domain), frontend (src/components), marketing (docs/marketing）

Produce three lists against the catalog

1. Suggested mounts：when matches the profile and requires is satisfied and is not currently mounted and is not in retired.txt → givemount method(user-level/project-level) and the reason.
2. Suggested unmounts: currently mounted but when does not match or requires is not satisfied or tier=project yet is mounted in a user-level persistent slot → suggest unmounting (and point out where to find the installation source).
3. Gaps: capabilities the profile shows are needed but for which the cataloghas nocorresponding skill (e.g., system/environment maintenance is currently missing) → state plainly "no skill available yet; can be added later."

For each item give: skill name · reason (matched when tags) · requires satisfaction status · installation coordinates (local true source link / skills.sh npx skills add NinjaSln-labs/agent-skills / SkillHub）。

Output format

## Skill Fit — <项目名>
画像：语言=… · git=… · 测试=… · CI=… · 阶段=… · 已挂=N（用户级 a / 项目级 b）

### 建议挂（N）
- <skill> — 命中 when=[…]；requires 满足；怎么挂：<命令>

### 建议摘（N）
- <skill> — when 不命中 / requires 缺 <x>；原安装源：<…>

### 缺口（N）
- <能力> — catalog 无对应技能（可后补）

### 反馈
本次建议你采纳了哪些？否决了哪些为什么？（写入下方反馈文件）

Feedback loop (continuous improvement)

• Local record(default): write .skill-fit/feedback/<YYYY-MM-DD>-<project>.md, including: profile signals + three lists + user adoption/rejection. On the next run, read the history to avoid repeated suggestions and calibrate when/requires。
• External user feedback channel = GitHub Issue(public repo NinjaSln-labs/agent-skills）：--share when available, generate a redacted report and deliver it in order——
  1. Has gh：gh issue create --repo NinjaSln-labs/agent-skills --title "[skill-fit] <项目类型> · 反馈" --body-file <报告路径> --label enhancement
  2. No gh: print the prefilled URL https://github.com/NinjaSln-labs/agent-skills/issues/new?title=<编码标题>&body=<编码正文>, for the user to submit manually
  • Redaction policy: includes only "project type profile (language/framework · whether git · whether tests · stage) + three lists + decisions + this skill's version";does not includelocal paths, repository names, credentials, or code content.Must be shown to the user for confirmation before submission。
• Once stable (v2), add "generation + executable installation" (one-click execution of mount/unmount/optional-install commands).

Anti-patterns

• agent Autonomously invokingthis skill (should wait for the user /skill:skill-fit）
• Adding or removing mounts without confirmation (v1 is read-only)
• Recommendations whose basis departs from catalog.yaml and self-invented lists (dual source)
• Writing registry occupancy status into the catalog (should be queried in real time)
• Ignore requires(push git-workflow to environments without git installed)
• Feedback log embellishment/missed rejection
• Submitting feedback as a GitHub Issue without user confirmation (or reporting without redaction)
• Copying catalog.yaml into the skill directory as a default value (dual-source drift)
• When catalog is missingnot declaringdegradation, treating inferred results as single-source facts

Completion criteria

• explicitly triggered by user /skill:skill-fit (not agent-autonomous)
• Profile signals detected (language/framework · VCS · test/CI · stage · current mounts)
• Three lists produced (suggest mount / suggest unmount / gaps), each with rationale + requires determination + install coordinates
• notmodifying any skill or mount (read-only)
• Feedback log written (including adoption/rejection);--share report delivered as a GitHub Issue after user confirmation (redacted, no local paths/credentials)
• Data sources resolved per the "locating order"; when catalog is missing,explicitly declaredas frontmatter inference degradation

Methodology sources (2026-09 research)

• Agent Skills spec optional fields:compatibility(environment prerequisites),metadata、disable-model-invocation(user-invoked only) — see agentskills.io spec and Pi/Claude Code field tables
• Progressive disclosure (metadata always resident, body on demand) — the basis for skill adaptation and token budgeting
• Operational stance:catalog.yaml single source + registry real-time lookup (to prevent dual-source)