Research For Skills

Research for Skills

Skill creation pipeline with dual-model review and self-learning. Thin orchestrator — delegates research to web-research, comparison to Codex sidecars, and testing methodology lives inline in authoring-rules.md (TDD enforced via development-lifecycle).

When to Trigger

• Forge's skill gap check finds no matching skill
• User asks to create or improve a skill
• Existing skill flagged needs_refresh (see improvement-loop.md)
• Plugin version change detected (via local plugin tracker, if maintained)

Process (10 Steps)

Step 1: Scope

If invoked from gap-detection (pre-filled scope in prompt):

• Skip scoping questions -- domain, criticality, and context already provided
• Proceed to Step 2 with pre-filled scope

Ask (one at a time):

1. What domain/topic? New skill, refresh, or repair?
2. Universal expert-grade or project-specific? (usually universal)
3. Mandatory subtopics?

Step 2: Resolve Active Corpus

Identify all existing skills that may overlap. See comparison-engine.md for full methodology.

# Custom skills
ls ~/.claude/skills/*/SKILL.md

# Plugin skills — resolve from installed_plugins.json, NOT raw cache
cat ~/.claude/plugins/installed_plugins.json | grep installPath

Critical: Never scan ~/.claude/plugins/cache/ directly — stale versions will double-count.

Step 3: Build/Refresh Inventory

Extract normalized records for matched skills. Cache to ~/.claude/skills/_meta/inventory.json. See comparison-engine.md for record format and refresh rules.

Step 4: Generate Comparison Shortlist

Shortlist 3-8 relevant skills (direct matches, adjacent domains, exemplars). Dispatch Codex skill_comparator sidecar in parallel:

CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)
codex exec --ephemeral -s read-only \
  -o "$CODEX_WORK/skill-comparison.md" \
  "Read these skill files [PATHS] and compare: coverage, patterns, gaps, quality for [DOMAIN]"

Step 5: Research

Delegate to web-research — do NOT duplicate research methodology here.

Optional: dispatch Codex docs_verifier sidecar for API/version claims:

Antigravity (agy) for freshness checks: Use a direct agy -p "..." Bash call to verify latest versions, deprecation status, and current best practices. Particularly useful for fast-moving domains where cached knowledge may be stale. agy returns plain text on stdout (parse text, not JSON fields). Complements Codex verification — run both in parallel when accuracy is critical. See the antigravity-cli skill for the invocation pattern.

agy --sandbox -p "Verify current as of 2026: latest stable version, deprecation status, and current best practices for [DOMAIN/LIBRARY]. List sources." < /dev/null

CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)
codex exec --ephemeral -s read-only \
  -o "$CODEX_WORK/docs-verify.md" \
  "Verify these claims are current as of 2026: [SPECIFIC CLAIMS]"

Step 6: Synthesize

Merge comparison + research findings. Extract:

• Best patterns from existing skills to incorporate
• Gaps no existing skill covers
• Decision: create new / update existing / skip

Check _meta/creation-log.jsonl for:

• Effective patterns in similar domains to incorporate
• Previous creation attempts for this domain (avoid repeating known failures)
• Failure deltas that indicate what went wrong last time

Check _meta/gap-events.jsonl for previous attempts at this domain:

• If domain was deferred 3+ times in 30 days: this is a proven need, prioritize creation
• If domain was created before but marked unhelpful: investigate why before recreating

Step 7: Draft Skill

Write using rules in authoring-rules.md. Key gates:

• Description starts "Use when..." — triggers only, NO workflow summary
• Anti-patterns table mandatory
• Word count: <500 frequent, <1200 standard
• Cross-model compatible language
• Specific data with sources, no vendor marketing as fact
• Ambiguity gate — REQUIRED for generation-type skills (skills whose primary output is an artifact: documents, images, pages, decks, code, posts). The SKILL.md must include a short "ask before generating" gate naming the 2-4 request dimensions that change the output materially, with the instruction to ask ONE compact clarifying question when they're missing rather than silently generating a guessed version. (Pattern precedent: forge Step 3 one-at-a-time questions, career-coach "No advice without context", career-application-writer Stage-0 intake + cold-start rule. Rationale: LLMs confidently answer the version of the question they think was meant; the cheapest quality lever is resolving ambiguity before generation.)
• FRESHNESS:v1 anchor (Evergreening v1, S041) — MANDATORY for new skills that carry any version/date/model-ID anchor. Add an HTML-comment <!-- FRESHNESS:v1 ... --> block (NEVER frontmatter — works in SKILL.md AND frontmatter-less references) declaring the tool/date/model you verified against, so the evergreen rot scanner can grade the skill instead of treating it as UNANNOTATED. Validate with python3 ~/.claude/skills/_meta/freshness.py lint <file> (advisory). Convention spec: docs/plans/2026-06-04-evergreening-design.md §6.5. (Same convention applies when the superpowers writing-skills plugin authors a skill — the FRESHNESS block is host-agnostic.)

Harness-orchestration authoring gate (HO-1..HO-7, S055) — MANDATORY when a skill might fan out

A skill that wants to fan work out across agents/workflows MUST satisfy ALL of these. Full guidance + copy-paste templates: references/harness-orchestration.md.

• HO-1 OPTIONAL — orchestration is a fast path, never a dependency; the documented MAIN path completes with ZERO orchestration primitives.
• HO-2 FEATURE-DETECTED — capability checks via probe.sh get capabilities.* ONLY (never inline probing, never raw jq on inventory.json); capabilities.* alone NEVER authorizes orchestration — the context conjunct (probe.sh context == main-loop / tool-list check) is mandatory (session files are shared with subagents).
• HO-3 FALLBACK-FIRST — the portable flow is the PRIMARY instructions; the fast path is a clearly-fenced enhancement using the conditional template.
• HO-4 CONTEXT-AWARE — the skill states its subagent behavior: portable flow, or emit a plan ARTIFACT (data, never executable JS — S052) and halt.
• HO-5 SCHEMA TWINS — canonical JSON Schema in the skill's schemas/; the companion workflow embeds the SCHEMA-TWIN-annotated literal (G-W2); the schema is REGISTERED (_meta/schemas/registry.v1.json).
• HO-6 COMPANION WORKFLOW — ship one ONLY IF: inline-main-loop primary callers AND stable reusable fan-out (≥3 sequential stages or ≥2 parallel agents) AND deterministic stage boundaries AND schema-checkable outputs. MUST NOT when: knowledge-only skill; mid-flow user interaction (G-W4); machinery-under-worktree (G-W6); primary callers are agents. Shipping triggers G-W7 registration.
• HO-7 HOST-NEUTRAL — all protocol text names CAPABILITIES, not Claude-only tool names ("the agent-spawn facility (Agent on Claude Code; see tool-mapping for Codex/Copilot)"); every plan/report artifact is host-neutral data executable serially by any host; only workflow compilation is described as Claude-main-loop-only; the skill DESCRIPTION never names Workflow/native teams (CSO pollution on other hosts).

Step 8: Review Gates

Local checks: frontmatter, word count, description format, anti-patterns table, CSO keywords.

Codex skill_challenger (mandatory for new skills, optional for minor updates):

CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)
codex exec --ephemeral -s read-only \
  -o "$CODEX_WORK/skill-challenger.md" \
  "Review this skill draft at [PATH]. Check: missing triggers, vague sections,
   outdated claims, structural bloat, CSO quality. Output: deploy / revise / rewrite."

Integrate feedback. If "revise": fix and re-run. If "rewrite": return to Step 7.

Step 9: Deploy

1. Backup before deploy: If skill directory already exists, cp SKILL.md SKILL.md.bak
2. Save skill to ~/.claude/skills/<name>/SKILL.md
3. If skill proves defective after deploy: mv SKILL.md.bak SKILL.md to restore
4. Log backup action in creation-log.jsonl
5. Verify no naming conflicts
6. Symlink to Codex (mandatory unless the skill dir contains a .no-codex-symlink sentinel):

   if [ ! -e "$HOME/.claude/skills/$SKILL_NAME/.no-codex-symlink" ]; then
     ln -sfn "$HOME/.claude/skills/$SKILL_NAME" "$HOME/.codex/skills/$SKILL_NAME"
   fi
   

7. Verify skill appears in available skills list

Symlink gating rule (single source of truth — no hardcoded list to maintain): symlink every new skill into ~/.codex/skills/ UNLESS the skill dir contains a .no-codex-symlink sentinel file (affordance-advisor precedent — host-gated skills that must not load on other CLIs). To exempt a skill, drop the sentinel: touch ~/.claude/skills/<name>/.no-codex-symlink.

Step 10: Log & Learn

Append to ~/.claude/skills/_meta/creation-log.jsonl:

{"date":"YYYY-MM-DD","skill":"name","action":"created|updated|refreshed","research_level":"SHORT|MEDIUM|LONG","sources":["..."],"comparison_skills":["..."],"codex_reviews":["skill_comparator","skill_challenger"],"patterns_used":["..."]}

See improvement-loop.md for failure tracking and refresh thresholds.

Skill Update Flow

1. Read current skill + all failure deltas from _meta/failure-deltas.jsonl
2. Run comparison engine against current plugin versions
3. Run targeted web-research for specific gaps
4. Update skill, addressing each promoted eval case
5. Verify Codex symlink (skip if .no-codex-symlink sentinel present): test -e ~/.claude/skills/<name>/.no-codex-symlink || test -L ~/.codex/skills/<name> || ln -sfn ...
6. Log update to creation-log.jsonl

Integration with Forge

When forge detects a skill gap:

"This task involves [DOMAIN]. No matching skill found.
  A) Research and create a skill first (runs this flow)
  B) Proceed without specialized skill
  C) Skip — general knowledge is enough"

If A: run Steps 1-10, return to forge with new skill available.

Cross-Model Compatibility

See authoring-rules.md for full guidelines. Key rule: use tool-agnostic language ("Read the file" not "Use the Read tool").

Cross-tool portability

When authoring a skill that must work across multiple AI CLIs (Claude Code, Antigravity CLI (agy), Codex CLI, GitHub Copilot CLI), read cross-tool-portability/cross-tool-portability.md first. It contains strict rules for frontmatter (only name + description), naming (^[a-z0-9-]+$, ≤64 chars), body length (<500 lines), install symlink pattern, AGENTS.md canonicalisation, hooks portability, and the 5 most common breaking mistakes.

Validate any new cross-tool skill against cross-tool-portability/scripts/verify-skill-portability.sh before publishing:

bash ~/.claude/skills/research-for-skills/cross-tool-portability/scripts/verify-skill-portability.sh \
  ~/.claude/skills/<name>/SKILL.md

Exit 0 = portable. Non-zero = fix the reported issue.

The sub-skill files:

Anti-Patterns