Use when packaging skills for deployment across multiple AI agent terminals (Claude Code, Copilot CLI, Cursor, Codex, Gemini CLI, OpenClaw), configuring the ~/.agents/skills/ cross-agent directory with symlink strategies, resolving agent-specific frontmatter conflicts, generating skills-manifest.json for auto-discovery, or testing skill compatibility across 6+ platforms. Handles the ~/.agents/skills/ standard (symlink-based sharing, manifest-based auto-discovery), symbolic link strategy, frontmatter normalization (strip vendor fields, validate per spec), manifest generation (skills-manifest.json, incremental rebuild, semver), and cross-agent compatibility testing (load per agent, verify routing, benchmark tokens, compatibility report). Do NOT use for skill content authoring, agent runtime behavior (use agent-eval-pipeline), platform-specific optimization, or CI/CD setup (use ci-cd-builder).
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Use when packaging skills for deployment across multiple AI agent terminals (Claude Code, Copilot CLI, Cursor, Codex, Gemini CLI, OpenClaw), configuring the ~/.agents/skills/ cross-agent directory with symlink strategies, resolving agent-specific frontmatter conflicts, generating skills-manifest.json for auto-discovery, or testing skill compatibility across 6+ platforms. Handles the ~/.agents/skills/ standard (symlink-based sharing, manifest-based auto-discovery), symbolic link strategy, frontmatter normalization (strip vendor fields, validate per spec), manifest generation (skills-manifest.json, incremental rebuild, semver), and cross-agent compatibility testing (load per agent, verify routing, benchmark tokens, compatibility report). Do NOT use for skill content authoring, agent runtime behavior (use agent-eval-pipeline), platform-specific optimization, or CI/CD setup (use ci-cd-builder).
author
Sandeep Kumar Penchala
license
MIT
portability
works with Claude Code, Copilot CLI, Cursor, OpenClaw, Gemini CLI
Portability target: Works on Claude Code, Copilot CLI, Cursor, OpenClaw, Gemini CLI, Codex, OpenCode. No vendor-specific frontmatter fields in core.
A veteran platform engineer's playbook for packaging skills that deploy uniformly across 15+ AI agent terminals — using the emerging ~/.agents/skills/ cross-agent standard with symbolic link strategies, frontmatter normalization pipelines, manifest-based auto-discovery, and cross-agent compatibility verification.
Cross-Skills Integration
Step
Skill
What it produces
Before
platform-engineer, devops-engineer
Infrastructure for shared directories, CI/CD pipeline for skill deployment
This is a HARD GATE. Do not produce ANY output, code, strategy, design, or recommendation without completing this research.
Before you act, you MUST execute every applicable research step. Research-before-acting is the difference between professional work and amateur guessing:
#
Research Step
Why It Matters
Where to Look
RP1
Verify domain currency. Check for breaking changes, deprecations, new standards, or version shifts since the knowledge cutoff.
[STALE_RISK] Outdated advice breaks real systems. API deprecations, framework version bumps, and security advisory changes happen continuously. Outputting based on stale knowledge damages credibility and produces broken results.
Official docs, changelogs, GitHub releases, RFC tracker
RP2
Audit the system or codebase. Read relevant files. Understand existing patterns, constraints, and architecture before proposing changes.
[CONTEXT_VIOLATION] Solutions that ignore existing patterns create technical debt. A change that contradicts the established architecture is worse than no change — it introduces inconsistency that compounds over time.
Cross-reference claims against authoritative sources. Every factual assertion needs a verifiable source. Mark each: [VERIFIED], [COMPUTED], or [ESTIMATED].
[HALLUCINATION_GUARD] Claims without sources are indistinguishable from hallucinations. The #1 cause of incorrect output is treating assumptions as facts. Source tagging prevents this.
Official documentation, peer-reviewed papers, RFCs, specifications
RP4
Identify known failure modes. Before recommending, list what commonly breaks. For each failure mode: trigger condition, detection signal, and mitigation.
[FAILURE_BLINDNESS] Every domain has known failure patterns. Output that doesn't address them is dangerously incomplete. If you cannot name 3+ failure modes for your recommendation, you don't understand it well enough to recommend it.
Quantify impact in concrete units. Replace abstract claims ("faster," "better," "more scalable") with exact numbers, even if estimated.
[VAGUENESS_PENALTY] "Faster" is unverifiable. "Reduces p95 latency from 340ms to 120ms (±15ms)" is verifiable. Abstract adjectives hide ignorance behind confidence. Concrete numbers expose gaps.
Benchmarks, production metrics, pricing data, published performance data
RP6
Map side effects and downstream impacts. What else breaks? Which dependencies are affected? Which downstream consumers need updating?
[CASCADE_BLINDNESS] Changes to one component ripple outward. A fix in module A can break module B that depends on A's old behavior. Map the blast radius before acting.
Dependency graph, cross-skill coordination table, API consumers list
RP7
Verify against non-negotiable quality gates. What are the minimum quality bars for this domain (accessibility, security, performance, accuracy, compliance)?
[QUALITY_FLOOR] Every domain has minimum standards below which output is invalid regardless of functionality. Missing WCAG AA = broken. Leaking credentials = broken. Silent data loss = broken.
Declare explicit limitations and edge cases. What does this NOT handle? What are the known boundaries? What scenarios are explicitly out of scope?
[SCOPE_HONESTY] Declaring limitations is a feature, not an admission of weakness. It prevents misuse, sets correct expectations, and demonstrates true understanding. Every solution has boundaries — naming them is professional.
This SKILL.md, domain literature, edge case databases
If you skip any of these research steps, you are not producing quality output — you are guessing with confidence. Guessing wastes time, breaks systems, and destroys trust. The references, ground rules, and decision trees in this skill exist specifically to prevent guessing. Use them.
Compliance: Research must be executed before any substantial output. For each step, document findings inline in your response using [RESEARCHED] marker: [RESEARCHED: RP1 — Domain verified against changelog v2.4. No breaking changes since cutoff.]. Partial research = partial quality. Zero research = zero credibility.
🔄 Iterative Research Loop — Research at EVERY Decision Point, Not Just Entry
The RP1-RP8 cycle above is NOT a one-time gate. It fires continuously at every material decision point throughout the workflow:
Loop
When It Fires
What Re-research Validates
Loop 0: Pre-Action
Before producing ANY output, code, strategy, or recommendation
At every adjustment, phase transition, scale-out, or significant state change
Has the context changed? Are the original assumptions still valid? Has new information invalidated the Loop 0 conclusions?
Loop 2: Pre-Exit
Before closing, handing off, escalating, or declaring completion
Is the deliverable complete by the quality gates defined in RP7? Are all limitations declared (RP8)? Have failure modes been addressed (RP4)?
Loop 3: Post-Action
After completion: compare expected vs. actual outcome
What was the efficiency ratio (actual / theoretical max)? What learnings emerged? What should be fed back into the pattern database for future decisions?
Integration into Core Workflow:
Every decision point in a skill's Core Workflow must be marked with:
[RESEARCH LOOP: Re-execute RP1-RP8 before proceeding to next phase]
This ensures the agent pauses to re-verify ALL research dimensions before making the next decision. A skill that only researches at entry and then operates on auto-pilot is a skill that makes decisions on stale context.
Markers for output: At each loop, the agent outputs: [RESEARCHED: Loop N — RP1-RP8 re-verified. Key delta from previous loop: ...]
Why this matters: A decision made in Loop 0 may be catastrophically wrong by Loop 2 because the context changed. Markets move. Requirements shift. Dependencies update. The research loop catches context drift before it becomes output error.
Compliance: Research must be executed before any substantial output AND re-executed at every decision point. For each research loop, document findings inline. Partial research = partial quality. Zero research = zero credibility. Stale research = dangerous confidence.
Anti-Hallucination
Admit uncertainty. If you cannot determine the correct approach, ask — do not guess.
Flag your knowledge cutoff. If this project uses tools or patterns you have not seen, state your assumptions.
Never guess security. If work touches auth, payments, or PII, route to security-reviewer.
[VERIFIED] before any production guidance: Verify assumptions. Verify compatibility. Verify correctness.
Route the Request
Auto-Route (No User Input Required)
Evaluate these file-system conditions in order. First match wins — jump immediately.
#
Condition
Action
A1
file_exists("~/.agents/skills/core/") AND file_exists("skills-manifest.json") AND `find ~/.claude/skills/ -type l
wc -l > 0`
A2
file_exists("~/.claude/skills/*/SKILL.md") AND NOT file_exists("~/.agents/skills/")
Claude Code-only deployment detected. Jump to Decision Trees — Manifest Generation to set up cross-agent structure.
A3
file_exists("~/.copilot/skills/") AND file_contains("~/.copilot/config.yml", "skills")
Copilot CLI deployment detected. Jump to Decision Trees — Frontmatter Normalization.
A4
file_exists("~/.cursor/skills/") OR file_exists("~/.cursorrules")
Cursor deployment. Jump to references/per-agent-directory-mapping.md for Cursor-specific setup.
A5
file_contains(".github/workflows/*.yml", "skill") OR file_contains(".gitlab-ci.yml", "skill")
CI/CD pipeline for skills detected. Jump to Core Workflow — Phase 4 (CI integration).
A6
file_exists("package.json") AND file_contains("package.json", "\"next\"|\"react\"|\"vue\"")
Invoke frontend-developer instead. This is app development, not skill packaging.
A7
file_exists("Dockerfile") OR file_exists("docker-compose.yml") AND NOT file_contains("*", "skill")
Invoke docker-kubernetes instead. This is container infrastructure, not skill packaging.
Intent Route (Ask the User)
If no auto-route matched, use this intent tree:
What are you trying to do?
├── Set up ~/.agents/skills/ from scratch → Jump to "Core Workflow" — Phase 1
├── Symlink existing skills to multiple agent directories → Jump to "Decision Trees" — Symlink vs Copy
├── Resolve frontmatter conflicts between agent formats → Jump to "Decision Trees" — Frontmatter Normalization
├── Generate skills-manifest.json for auto-discovery → Jump to "Decision Trees" — Manifest Generation
├── Test if my skills work across all agents → Jump to "Decision Trees" — Agent Discovery Flow
├── Fix a skill that loads in Claude Code but fails in Copilot CLI → Jump to "Gotchas" — Cross-agent loading inconsistency
├── Migrate from single-agent skill deployment to cross-agent → Jump to "Core Workflow" — Phase 2
├── Set up CI/CD to auto-deploy skills to all agents → Jump to "Core Workflow" — Phase 4
├── Writing skill content (not packaging) → Invoke the specific skill's authoring template instead
├── Debugging agent runtime behavior → Invoke agent-eval-pipeline instead
└── Not sure? → Describe your deployment setup and which agents you target, I'll recommend the packaging strategy
Do not read the entire skill. Follow the route above and read only the sections it points to.
Ground Rules — Read Before Anything Else
These rules are negative constraints — they define what you MUST NOT do, with mechanical triggers that detect violations before execution.
#
Negative Constraint
Mechanical Trigger (detect before executing)
Violation Response
R1
REFUSE to symlink a skill without verifying all target directories exist. A symlink to a non-existent agent directory silently fails — the skill appears deployed but no agent can load it. Symlink creation without existence checks is the #1 cause of "deployed but invisible" skill bugs.
Trigger: ln -s command executed AND test -d ~/.${agent}/skills/ was NOT run first for ANY target agent
STOP. Run: for agent in claude copilot cursor codex gemini opencode; do mkdir -p ~/.${agent}/skills/; done before creating any symlinks.
R2
REFUSE to deploy a skill with vendor-specific frontmatter fields to Copilot CLI. Copilot CLI REJECTS skills containing unrecognized fields (cursorRules, geminiDirectives, codexOpenAPI, opencodeTOML). A skill that works perfectly in Claude Code will fail silently in Copilot CLI, producing no error — just an invisible skill.
Trigger: grep -E "cursorRules|geminiDirectives|codexOpenAPI|opencodeTOML" SKILL.md returns matches AND target includes copilot-cli
STOP. Run frontmatter normalization: strip vendor-specific fields before deploying to Copilot CLI. Use references/frontmatter-normalization.md for the field mapping.
R3
REFUSE to regenerate the full manifest when only one skill changed. Full manifest regeneration on every skill change causes manifest version churn, invalidates agent caches, and triggers unnecessary reloads across all agents. A 50-skill deployment regenerating the manifest on every single-skill update wastes 10+ seconds per deploy.
Trigger: manifest generation script runs without --incremental flag AND only one skill's SHA-256 differs from lock file
STOP. Use incremental manifest rebuild: detect changed skills via hash comparison, regenerate only affected entries. See references/skills-manifest-format.md.
R4
DETECT and WARN when a skill's portability field lists agents it hasn't been tested on. The portability field is a claim, not a warranty. Listing "works with Gemini CLI" when the skill has never been loaded in Gemini CLI creates false confidence that leads to production failures when someone actually tries it.
Trigger: portability field contains agent name AND no entry in compatibility-report-*.json for that agent within last 30 days
WARN: "The portability field claims compatibility with ${agent} but no compatibility test report exists for the last 30 days. Run scripts/verify-skill.sh with --compatibility-test flag or update the portability field to reflect actual tested agents."
R5
REFUSE to deploy a Claude Code skill without PROCESS_TREE.md. Claude Code (as of 2026-07) requires PROCESS_TREE.md in each skill directory for detection. Without it, the skill is invisible to Claude Code — no error, no warning, just silent non-discovery. This is tracked in Claude Code issue #31005.
Trigger: target includes claude-code AND test -f ~/.agents/skills/core/<skill>/PROCESS_TREE.md returns false
STOP. Generate PROCESS_TREE.md from the skill manifest before deploying to Claude Code. See references/claude-code-specific-patterns.md.
R6
DETECT and WARN about broken symlinks across any agent directory. Agent upgrades that change directory structure silently break symlinks. A Claude Code upgrade that moves from ~/.claude/skills/ to ~/.claude/agents/skills/ breaks every symlink — and no agent reports the breakage.
Trigger: find ~/.claude/skills/ ~/.copilot/skills/ ~/.cursor/skills/ -type l ! -exec test -e {} \; -print returns any paths
WARN: "Found ${count} broken symlinks. This typically happens after agent upgrades that change directory structures. Run 'Cross-Skill Coordination' → symlink health check to repair."
R7
ANCHOR to runtime versions before generating framework-specific code. Never generate Fastify/Express/Django/FastAPI/Prisma/SQLAlchemy API calls from training data alone — your training data may be stale.
Trigger: skill receives code-generation task involving framework-specific APIs → run scripts/runtime-version-detect.sh [project-root] --skill-context to detect installed versions → if detection succeeds, anchor all API calls to detected versions → if detection fails, request version info from user
STOP. Respond: "Detected: {runtime}@{version}, {frameworks}@{versions}. Anchoring all API calls to these versions. I will add // VERIFY: comments on any API call where the detected version is newer than my training cutoff."
R8
RUN the ROI Gate before any non-emergency code change. Every code change that is not (a) a security fix, (b) a compliance requirement, or (c) an active production incident must pass scripts/roi-gate.sh. If the gate returns negative, refuse to write the code.
Trigger: skill receives a code-generation or refactoring task that is NOT a security fix, compliance requirement, or production incident → estimate implementation cost in engineer-hours → compare against annual value of the change → if cost > value, gate fails
STOP. Respond: "ROI Gate analysis: This change costs approximately $[X] to implement but saves $[Y]/year. Payback period: [N] years. If payback > 2 years, I recommend declining this work. See scripts/roi-gate.sh for the full formula."
Admit uncertainty — never fabricate. If you're not certain about an API method, package version, configuration syntax, or command flag, say so explicitly: "I'm not certain this API exists in the latest version. Check the official docs at [URL]." Never invent a function signature or configuration key because it "seems right." Hallucinated code costs hours of debugging.
Flag your knowledge cutoff. If your training data predates the latest SDK release, framework version, or platform change, state your cutoff date and recommend verifying against current documentation. This is especially critical for rapidly evolving domains: cloud IAM policies, JS framework APIs, mobile OS capabilities, and SaaS pricing — all change quarterly or faster.
Never guess security configurations. If you're unsure about the correct CSP header value, OAuth flow parameter, or encryption algorithm choice, do NOT provide a "reasonable default." Say: "Security configurations must be verified against current best practices at [official source]. I cannot provide a definitive answer without current documentation."
Distinguish between what you know and what you infer. Explicitly mark statements as: [VERIFIED] — from official docs, [COMMON-PRACTICE] — widely used but not authoritative, [INFERRED] — your best guess based on patterns, [UNKNOWN] — you're unsure. This helps the user calibrate trust in your output.
The Expert's Mindset
Masters of cross-agent skills packaging don't just deploy — they build resilient distribution pipelines that survive agent upgrades, format changes, and ecosystem fragmentation. They think in systems, not one-off symlinks.
Cognitive Bias
Mitigation
Single-agent myopia — optimizing for one agent's quirks at the expense of others
Before making any agent-specific decision, ask: "Does this break any other agent in the portability list?"
Symlink-and-forget — assuming symlinks are permanent infrastructure
Run symlink health checks in CI daily; treat symlinks as infrastructure that requires monitoring
Manifest stagnation — generating the manifest once and never updating it
Hook manifest regeneration into pre-commit and CI; stale manifests are invisible skills
Frontmatter cargo-culting — copying frontmatter from one agent to another without normalization
Run the normalization pipeline for every target agent; never hand-edit agent-specific frontmatter
What Masters Know That Others Don't
The failure modes of every symlink strategy — when relative symlinks break, when absolute symlinks survive upgrades, when copies are safer
When not to use the cross-agent standard (single-agent deployments, agent-specific plugins that can't be normalized)
That frontmatter validation is agent-specific — what Claude Code silently ignores, Copilot CLI fatally rejects
When to Break Your Own Rules
Skip PROCESS_TREE.md if issue #31005 is resolved. Once Claude Code supports manifest-based discovery, drop the redundant file.
Copy instead of symlink for rapid iteration. During active skill development, copy to avoid chasing symlink resolution bugs. Re-symlink when stable.
Operating at Different Levels
Level
Scope
You...
L1
Single skill, single agent
Normalize one skill's frontmatter for one target agent; create a symlink
L2
Multiple skills, 3-5 agents
Set up ~/.agents/skills/ structure; generate manifest; deploy symlink tree for a team's skill set
L3
Organization-wide skill fleet, 6+ agents
Design the packaging pipeline; automate normalization and deployment; establish compatibility testing gates
L4
Platform / ecosystem
Define cross-agent directory standards; build tooling adopted by multiple organizations; contribute to agent terminal skill loading specs
L5
Industry / ecosystem
Create new packaging standards adopted across the AI agent industry; redefine how skills are distributed and discovered
Default level for this skill: L2
For full level definitions, see skills/00-framework/skill-levels/SKILL.md.
When to Use
Setting up ~/.agents/skills/ as a shared skill directory for multiple AI agent terminals
Symlinking skills from a central core directory to per-agent skill directories (Claude Code, Copilot CLI, Cursor, Codex, Gemini CLI, OpenCode, OpenClaw, Windsurf, Cody, Continue, Aider, Amazon Q)
Resolving frontmatter conflicts: a skill loads in Claude Code but Copilot CLI rejects it with "unrecognized field" errors
Generating skills-manifest.json for agent auto-discovery — so agents know what skills exist without scanning the filesystem
Running compatibility tests to verify a skill loads, routes, and executes correctly across all target agents
Migrating from single-agent skill deployment (e.g., Claude Code-only ~/.claude/skills/) to cross-agent deployment
Setting up CI/CD pipelines that auto-deploy skills to all agent directories on push
Debugging "skill deployed but invisible" issues — the skill exists on disk but the agent can't find it
Creating per-agent overrides when a skill needs different content for different agents
Building tooling that normalizes skill frontmatter for each agent's expected format
Decision Trees
1. Symlink vs Copy Decision
┌─────────────────────┐
│ START: Is this │
│ skill identical │
│ across ALL target │
│ agents? │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ YES │ NO
┌────▼────────┐ ┌───────▼──────────┐
│ Does any │ │ Which agent(s) │
│ agent need │ │ need different │
│ PROCESS_TREE │ │ content? │
│ or special │ └──┬───────────┬───┘
│ body content?│ │ │
└──┬───────┬───┘ ┌────▼───┐ ┌────▼──────────┐
│YES │NO │ COPY to│ │ Can frontmatter│
┌────▼──┐ ┌──▼────┐│ over- │ │ normalization │
│ COPY │ │SYMLINK││ rides/ │ │ resolve it? │
│ to │ │from ││ <agent>│ └──┬─────────┬───┘
│ over- │ │core/ ││ + sym- │ │YES │NO
│ rides/│ │to all ││ link │┌────▼────┐┌──▼──────────┐
│ <agent│ │agent ││ over- ││ SYMLINK ││ COPY to │
│ > │ │dirs ││ ride ││ from ││ overrides/ │
└───────┘ └───────┘└────────┘│ core/ ││ <agent>/ + │
└─────────┘│ symlink │
└─────────────┘
Symlink for shared skills — 95% of cases. Single source of truth, zero duplication.
Copy for overrides — when an agent needs PROCESS_TREE.md (Claude Code), Google-style directive blocks (Gemini CLI), or different body content.
What good looks like: The normalization pipeline is deterministic — same input produces same output every time. It's run as a build step, not a manual process. Every target agent gets a validated, field-correct copy.
3. Agent Discovery Flow
┌──────────────────────────────┐
│ START: Agent terminal │
│ starts up / reloads config │
└────────────┬─────────────────┘
│
┌────────────▼─────────────────┐
│ 1. SCAN: Agent reads its │
│ skill directory │
│ ~/.<agent>/skills/ │
└────────────┬─────────────────┘
│
┌────────────▼─────────────────┐
│ 2. RESOLVE: Follow symlinks │
│ to actual skill locations │
│ (or read copied overrides) │
└────────────┬─────────────────┘
│
┌────────────▼─────────────────┐
│ 3. READ MANIFEST: If │
│ skills-manifest.json exists, │
│ use it for skill metadata │
│ Else, parse each SKILL.md │
└────────────┬─────────────────┘
│
┌────────────▼─────────────────┐
│ 4. VALIDATE: Check front- │
│ matter fields, required │
│ fields, field types │
│ Claude: silent ignore │
│ Copilot: REJECT on unknown │
│ Cursor: generate rules │
└────────────┬─────────────────┘
│
┌────────────▼─────────────────┐
│ 5. LOAD: Include skill in │
│ agent's available_skills │
│ block. Skill is now │
│ invocable by name. │
└────────────┬─────────────────┘
│
┌────────────▼─────────────────┐
│ 6. VERIFY: (Optional) Agent │
│ runs compatibility check — │
│ loads, routes, executes │
│ Logs any warnings. │
└──────────────────────────────┘
What good looks like: All agents discover all skills within 2 seconds of startup. Zero "deployed but invisible" bugs. Manifest-driven discovery eliminates filesystem scanning overhead.
4. Conflict Resolution
┌───────────────────────────────┐
│ START: Two agents disagree │
│ on a frontmatter field │
│ (e.g., token_budget: Claude │
│ uses 4000, Copilot uses 3000)│
└─────────────┬─────────────────┘
│
┌─────────────▼─────────────────┐
│ Is this a CORE field (name, │
│ description, version)? │
└──────┬──────────────────┬─────┘
│YES │NO
┌──────▼──────┐ ┌───────▼──────────┐
│ Use common │ │ Can the field be │
│ subset. │ │ different per │
│ Both agents │ │ agent without │
│ agree on │ │ breaking skill │
│ core fields.│ │ functionality? │
│ Log conflict│ └──┬───────────┬────┘
│ in manifest.│ │YES │NO
└─────────────┘ ┌────▼────┐ ┌───▼──────────┐
│ Per-agent│ │ Choose one │
│ override │ │ value as │
│ in over- │ │ canonical. │
│ rides/ │ │ Document why │
│ <agent>/ │ │ in manifest │
│ SKILL.md │ │ conflicts[]. │
└──────────┘ │ Warn on load │
│ for other │
│ agent. │
└──────────────┘
Common subset strategy: For fields both agents require but interpret differently, use the most restrictive interpretation that satisfies both.
Per-agent override: For cosmetic or non-functional differences (token_budget, display preferences), create per-agent overrides.
Canonical wins: For behavioral differences that can't be split, document the choice in the manifest's conflicts[] array.
5. Manifest Generation
┌────────────────────────────────┐
│ START: Generate skills- │
│ manifest.json │
└──────────────┬─────────────────┘
│
┌──────────────▼─────────────────┐
│ 1. SCAN: Walk ~/.agents/ │
│ skills/core/*/ directories │
│ For each, find SKILL.md │
└──────────────┬─────────────────┘
│
┌──────────────▼─────────────────┐
│ 2. EXTRACT: Parse YAML front- │
│ matter from each SKILL.md │
│ Collect: name, description, │
│ version, author, tags, deps │
└──────────────┬─────────────────┘
│
┌──────────────▼─────────────────┐
│ 3. HASH: Compute SHA-256 of │
│ each skill's directory tree │
│ Compare with lock file hashes │
│ Changed? → Mark for update │
└──────────────┬─────────────────┘
│
┌──────────────▼─────────────────┐
│ 4. RESOLVE DEPS: Build dep │
│ graph from chain.consumes_from │
│ Detect circular dependencies │
│ Topological sort for load order│
└──────────────┬─────────────────┘
│
┌──────────────▼─────────────────┐
│ 5. DETECT OVERRIDES: Check │
│ overrides/<agent>/<skill>/ │
│ For each override, add to │
│ skill entry's overrides map │
└──────────────┬─────────────────┘
│
┌──────────────▼─────────────────┐
│ 6. DETECT CONFLICTS: Compare │
│ frontmatter across overrides │
│ If field values differ between │
│ agents → add to conflicts[] │
└──────────────┬─────────────────┘
│
┌──────────────▼─────────────────┐
│ 7. WRITE: Output skills- │
│ manifest.json + .lock file │
│ with versions, hashes, stats │
└────────────────────────────────┘
Incremental mode: If skills-manifest.lock exists, only regenerate entries for skills whose SHA-256 differs. This reduces manifest regeneration from O(N) to O(changed) — critical for 50+ skill deployments.
Error Recovery
If a command or approach fails, follow this escalation path before giving up:
Symptom
First Action
If That Fails
Last Resort
Tool/command not found
Check installation: which [tool] or [tool] --version. Install via package manager (brew install, npm install -g, pip install)
Check PATH: echo $PATH. Verify the tool binary is in a PATH directory. Symlink or update PATH if installed but unreachable
Use a functionally equivalent alternative tool. If rg is unavailable, use grep -r. If gh is unavailable, use git directly or the GitHub API via curl
Permission denied
Check ownership: ls -la [path]. Fix with chmod or sudo if appropriate. For API errors (401/403), verify credentials haven't expired: echo $TOKEN or check ~/.netrc
Refresh credentials: re-authenticate with the service. For file permissions, check if the file is locked by another process: lsof [path]
Request elevated permissions or use a different authentication method (token vs password, SSH key vs HTTPS)
Command hangs or times out
Kill the process: Ctrl+C. Re-run with a timeout: timeout 30 [command] or gtimeout on macOS. Check system resources: top, df -h, netstat -an
Add verbose/debug flags: --verbose, --debug, -v. Check logs: tail -f [logfile]. Reduce scope: process fewer files, query a smaller time range, limit concurrency
Split the work into smaller batches. Implement a retry loop with exponential backoff (1s, 2s, 4s, 8s). If the issue is network-related, add --retry 3 or equivalent
Unexpected output or error message
Read the error message completely — the solution is often in the last 3 lines. Search the exact error: grep -r "[error text]" in the repo to find prior occurrences
Check GitHub issues for the tool: gh issue list --repo owner/repo --search "[error keyword]". Check Stack Overflow
Simplify the approach. If the complex one-liner fails, break it into 3 sequential commands. If the specialized tool fails, use a more basic tool with more steps
Data integrity concern (wrong output, silent failure)
Verify with a manual check: compare output against a known-correct baseline. Add assertions: `[command]
grep -q "[expected]" && echo "OK"
Hard failure boundary: If 3 different approaches all fail, STOP. Do not iterate infinitely. Log what was tried, capture the error output, and report the blocking issue with full context. Move to the next independent task rather than blocking all progress on one failure.
Cross-Skill Coordination
Cross-agent skills packaging sits at the intersection of platform engineering, DevOps, and agent evaluation. It bridges the gap between skill content authoring and runtime deployment.
Decision Gates & Artifacts
Gate 1 — Infrastructure Exists:~/.agents/skills/ directory structure provisioned by platform-engineer. Artifact: directory tree with correct permissions and environment variables.
Gate 2 — CI/CD Pipeline Ready: Automated deployment pipeline set up by devops-engineer or ci-cd-builder. Artifact: GitHub Actions workflow or equivalent that runs on push to skill directories.
Gate 3 — Skills Authored: Skill content (SKILL.md, references/) produced by individual skill specialists. Artifact: complete skill directory with validated frontmatter, references, and optional scripts.
Gate 4 — Compatibility Verified: Skills tested across all target agents by this skill. Artifact: compatibility report matrix proving the skill loads and routes correctly on every agent.
Artifact: Cross-agent deployment report (symlink tree status, manifest.json, compatibility matrix, broken link count).
Security review of symlink strategy or manifest injection vectors
security-reviewer
Upstream Skill
What You Receive
When to Involve
system-architect
System context, integration points, architectural constraints
Before specialized implementation — understand the system it fits into
Proactive Triggers
Trigger
Notify
Why
Any agent terminal announces a new major version with skill system changes
Platform Engineer, All Skill Authors
Preemptive compatibility check; update normalization rules before breakage
skills-manifest.json shows >5% of skills with version conflicts
All Skill Authors, DevOps
Version drift accelerating; lock file reconciliation needed
Symlink health check finds >0 broken symlinks for 3+ consecutive days
Platform Engineer, DevOps
Persistent infrastructure issue; agent upgrade or filesystem problem
New ~/.agents/skills/ standard version released (v2.0 schema)
All Skill Authors, Platform Engineer
Schema migration; manifest format update; backward compatibility planning
Skill deployment CI/CD pipeline run time exceeds 5 minutes
DevOps, Platform Engineer
Pipeline optimization needed; incremental manifest rebuild or parallel symlink creation
Manifest lock file grows beyond 500KB (50+ skills with full metadata)
Platform Engineer
Performance concern; consider manifest sharding or lazy loading
Copilot CLI frontmatter rejection rate exceeds 10% of deployed skills
Skill Authors
Frontmatter normalization pipeline failing; vendor-specific field leakage
Core Workflow
Phase 1 (~15 min): Cross-Agent Health Audit
Input: Any system with ~/.agents/ or per-agent skill directories
...
📎 Full content (60 lines):references/core-workflow.md
Complete when: Audit report generated covering symlink health, manifest freshness, frontmatter validation, PROCESS_TREE.md coverage, and compatibility test matrix for all target agents.
Complete when: All consumers have acknowledged the deprecation/migration timeline in writing.
Complete when: Rollback plan documented with specific trigger conditions and revert steps.
Complete when: Performance benchmarks run and results within 10% of baseline.
Complete when: Documentation updated for all affected interfaces, SDKs, and developer guides.
Complete when: Stakeholder sign-off obtained from all impacted team leads.
Complete when: Monitoring dashboards created for new system with alert thresholds configured.
Complete when: Knowledge transfer session completed with operations team.
Error Decoder — War Stories from the Trenches
(STANDARD)
When this domain goes wrong, it goes wrong in predictable ways. Here are the most common failure signatures, their root causes, and the fix you'll reach for after you've been burned once.
Symptom
Root Cause
Fix
Lesson
Skill works perfectly in Claude Code, silently fails in Copilot CLI — no error, just doesn't load. Discovered when user asks "why isn't my skill showing up?"
Frontmatter field incompatibility: Claude Code uses type: skill, Copilot CLI uses category: development. The type field is ignored by Copilot CLI but required by Claude Code. Missing fields cause silent loading failure, not an error
Maintain a frontmatter compatibility matrix: document which fields each agent requires, which are optional, and which cause silent failures. Use union frontmatter: include all fields needed by all target agents. Validate with skills-manifest.json schema check before packaging. Test loading in each target agent — not just "does the manifest parse?" but "does the agent actually use this skill?"
Frontmatter is the API contract between your skill and 6 different agent platforms. Silent failures are worse than errors — you ship a skill that "passes validation" but doesn't work. Test actual loading in every target agent, not just schema compliance
Symlink strategy: ~/.agents/skills/core/ → ~/.copilot/skills/ symlinks break after macOS update. All skills silently unavailable. User discovers when Copilot gives generic responses instead of domain-specific advice
macOS system updates can modify permissions on ~/ directories or break symlinks that cross filesystem boundaries. No symlink health check. No fallback if symlinks are broken — agents just don't see the skills
Add a symlink health check script: find ~/.agents/skills -type l ! -exec test -e {} \; -print — lists broken symlinks. Run on startup or in a cron job. Provide a repair script: repair-skills-symlinks that re-creates broken links. Implement a fallback: if shared skills directory is unreachable, load from a bundled copy in the agent's own skills directory
Symlinks are fragile across OS updates, disk migrations, and permission changes. Any system that depends on symlinks must have health checking and automatic repair. "It stopped working and nobody knew why" is the default failure mode of symlink-based architectures
skills-manifest.json lists 50 skills → 3 are duplicates with different names: code-reviewer, code-review, and review-code. Agent routing becomes non-deterministic — sometimes the right skill, sometimes the duplicate with stale config
No deduplication at packaging time. Skills created by different teams with slightly different names for the same domain. Manifest includes all discovered files without checking for functional overlap. Agent prompt picks the first skill matching a keyword, which may be the wrong one
Implement deduplication: before generating manifest, compare skill descriptions using cosine similarity. Flag any pair with >80% similarity. Enforce naming convention: domain-role format. Use aliases frontmatter field instead of creating duplicate skills. Manifest validation rejects duplicate skill names
Duplicate skills in the manifest create non-deterministic agent behavior. The agent picks "a" code review skill — but which one? If they have different ground rules, the output quality varies randomly. Deduplication at packaging time is the only fix
Skill with allowed-tools: Bash → deployed to Gemini CLI which doesn't support Bash tool. Skill silently skips any tool call that isn't available. User gets incomplete output with no error — the skill executed, it just couldn't do half its job
Tool availability varies by agent platform. A skill that requires Bash for its core workflow will produce partial results on agents without Bash support. The skill has no mechanism to detect or declare tool dependencies
Add required-tools frontmatter field separate from allowed-tools. Required tools cause the skill to refuse to load (with error message) on agents that don't support them. Allowed tools are optional enhancements. Test skill behavior when required tools are unavailable — it should fail loudly, not silently produce partial output
Skill portability is about knowing when NOT to run as much as knowing how to run everywhere. A skill that silently degrades on unsupported platforms is worse than one that refuses to load with a clear error. Partial output masquerading as complete output destroys trust
Cross-agent testing: manual testing across 6 terminals for every skill update takes 3 hours. Team skips testing for "minor" changes. A "minor" frontmatter fix breaks the skill on Cursor — discovered by users, not by tests
No automated cross-agent test harness. Manual testing is time-consuming and skipped under pressure. Each agent has different output formats, making automated comparison difficult
Build a test harness: define a test input, run it through each target agent with the skill loaded, and compare outputs. Test for: (1) skill loads without error, (2) skill routes correctly for key trigger phrases, (3) ground rules are actually followed in generated output. Use snapshot testing — flag when output behavior changes. Run in CI on every skill change
Manual testing across 6 platforms doesn't scale beyond 3 skills. Automated cross-agent testing is the only way to maintain quality as the skill library grows. The cost of setting up the harness is recovered in the first week of not doing manual testing
Agent-specific override file (~/.copilot/skills/code-reviewer/override.md) conflicts with core skill from ~/.agents/skills/core/code-reviewer/SKILL.md. Agent loads both, applies conflicting rules, produces inconsistent output
Merge strategy undefined: does the override supplement or replace? If both specify ground rules, which takes precedence? The agent sees two conflicting instructions and picks one arbitrarily — usually the most recent or the longest, creating non-deterministic behavior
Define explicit merge strategy: overrides always REPLACE their section, never supplement. Document the strategy in skills-manifest.json. Validate at load time: if an override and core skill specify the same section, warn the user. Provide an audit command: skill-diff code-reviewer shows the effective merged skill vs. core
Override semantics must be explicit and deterministic. "Both apply" with conflicting rules is the worst possible outcome — the agent resolves the conflict randomly, and the user gets different results on different runs. REPLACE semantics (override wins) is the only predictable strategy
State Log
This skill maintains a decision ledger to prevent context drift and ensure recall across sessions. Every major architectural choice, constraint decision, and trade-off must be recorded so that subsequent agents (or future sessions) can recover context without replaying the entire conversation.
What Good Looks Like
When cross-agent skills packaging is fully realized, every skill deploys identically across 15+ agent terminals from a single source of truth. The manifest is always current. Symlinks are always healthy. Frontmatter is always agent-validated. And when a new agent terminal emerges, adding it to the deployment is one config change and one pipeline run.
Vendor-specific fields only in overrides but unvalidated
All frontmatter validated per agent, no leakage
PROCESS_TREE.md coverage
Missing for any Claude Code skill
Present but >30 days since regeneration
Present and regenerated with manifest
Compatibility coverage
Portability lists untested agents
All agents tested but >90 days ago
All agents tested within 30 days
Deployment latency
>5 min to deploy a skill change
2-5 min
<2 min from push to all agents
Discovery reliability
Any agent fails to discover a deployed skill
All agents discover but >3s startup
All agents discover within 2s
The Litmus Test
Ask these three questions about your packaging deployment. If any answer is "no," you have work to do:
"If I add a new skill to core/ and push, does every agent discover it within 2 minutes without manual intervention?"
"If Claude Code releases v2.0 with a new skills directory path, does my deployment survive the upgrade without human debugging?"
"Can a new engineer deploy their first cross-agent skill in under 15 minutes by following the documented workflow?"
Deliberate Practice
graph LR
A[Package] --> B[Test across<br/>all agents] --> C[Fix<br/>compatibility<br/>gaps] --> D[Re-package<br/>with new<br/>agent support] --> A
Level
Practice
Frequency
Novice
Set up ~/.agents/skills/ from scratch with 3 skills, deploy to Claude Code + Copilot CLI, verify both load
Weekly
Competent
Add a new agent terminal to an existing deployment (one not in the original portability list); handle all normalization
Monthly
Expert
Design a normalization pipeline for a skill with 5+ agent-specific overrides; optimize manifest regeneration to <1 second
Quarterly
Master
Contribute a cross-agent packaging pattern to the ~/.agents/skills/ standard; mentor a team through their first cross-agent deployment
Quarterly
The One Highest-Leverage Activity: Every month, take a skill deployed 3+ months ago and run the full compatibility test matrix. Document every failure mode — these are the edges the normalization pipeline missed.
Gotchas
Symlink breaking on agent upgrade changing directory structure. When an agent terminal releases a new major version that reorganizes its config directory (e.g., Claude Code moving skills from ~/.claude/skills/ to ~/.claude/agents/skills/, or Copilot CLI changing from ~/.copilot/skills/ to ~/.config/copilot/skills/), every symlink breaks silently. No agent reports "I can't find my skills" — skills simply disappear from the available list. Engineers waste hours debugging "why did my skills stop working?" before discovering the directory change. Total cost: $10K-$50K in engineering time debugging broken skill references across teams of 10-50 engineers. An organization with 30 engineers losing 2 hours each to broken symlink debugging after an agent upgrade burns $15K-$30K in a single incident. Fix: Run symlink health checks in CI daily: find ~/.claude/skills/ ~/.copilot/skills/ -type l ! -exec test -e {} \; -print. Store agent base paths in variables (not hardcoded). Pin agent versions and test symlink paths before upgrading.
Frontmatter field silently dropped by agent. Claude Code silently ignores unrecognized frontmatter fields — no error, no warning. If you add cursorRules or geminiDirectives to a shared skill's frontmatter, Claude Code loads the skill perfectly but the field is absent from its context. The skill author assumes the field is active because the skill loads. Days or weeks later, someone tries to use the cursorRules-dependent feature and it doesn't work — but the skill loaded fine, so they blame the feature, not the packaging. Total cost: $5K-$20K in misdirected debugging. Teams chase "broken cursor rules" for 4-8 hours before realizing the field was never loaded. Multiply by the number of skills with vendor-specific fields leaking into the shared core. Fix: Frontmatter normalization MUST strip vendor-specific fields before deployment to agents that don't support them. Run grep -E "cursorRules|geminiDirectives|codexOpenAPI|opencodeTOML" on every SKILL.md in core/ — these fields don't belong there.
Cross-agent skill loading inconsistent: skill works in Claude Code but fails in Copilot CLI. The most common cross-agent failure mode: a skill with cursorRules in its frontmatter deploys to both Claude Code and Copilot CLI. Claude Code silently ignores cursorRules and loads fine. Copilot CLI encounters an unrecognized field and REJECTS the entire skill — no load, no error in user-facing UI, just an absent skill in <available_skills>. The skill author tests in Claude Code, sees it working, and marks it as "cross-agent compatible." The Copilot CLI users never see the skill and don't know it's supposed to exist. Total cost: $15K-$40K in wasted skill authoring effort. Skills authored and tested for Claude Code but deployed to Copilot CLI with a 30-50% silent failure rate represent thousands of hours of content that never reaches its intended audience. An organization with 20 cross-agent skills seeing 30% Copilot CLI failure rate wastes 6 skills × 40 authoring hours = 240 hours ($20K-$40K). Fix: Run the compatibility test matrix before claiming cross-agent compatibility. Every agent in the portability list must have a passing load test. See references/compatibility-testing-matrix.md.
Manifest staleness: new skills added but manifest not regenerated. A team adds 3 new skills to ~/.agents/skills/core/ but forgets to regenerate skills-manifest.json. The 3 new skills exist on disk and symlinks are correct, but agents that use manifest-based discovery (an increasing number) never see them. Agents that scan the filesystem directly (older versions) DO see them — creating an inconsistent state where some agents have the skills and others don't. The team deploys, tests on an older agent, sees the skills, and declares success. Meanwhile, newer agent versions are missing critical skills. Total cost: $8K-$25K in inconsistent deployment debugging. The "works on my agent" problem multiplied across a fleet of terminals. 3-5 person-days lost tracing why skills appear in Claude Code but not in Gemini CLI (which reads manifest). Fix: Hook manifest regeneration into pre-commit and CI. Never manually deploy skills without regenerating the manifest. Run diff <(jq -r '.skills[].name' skills-manifest.json | sort) <(ls ~/.agents/skills/core/ | sort) to detect skills on disk but not in manifest.
Agent-specific syntax leaking into shared skills. A skill author embeds Copilot CLI-specific directives in the SKILL.md body — e.g., referencing "the available_skills block" or using Claude Code's PROCESS_TREE.md convention as if it's universal. When this skill is deployed to Gemini CLI (which uses Google-style directive blocks in the body), the Copilot-specific references confuse Gemini CLI's directive parser. When deployed to Cursor, the Claude-specific conventions don't map to .cursorrules directives. The skill loads everywhere but produces incorrect or nonsensical behavior in non-target agents. Total cost: $10K-$30K in cross-agent behavior debugging. Skills that "load" but "act wrong" are the hardest bugs to catch — they pass load tests but fail behavioral tests. Each such bug costs 4-8 hours of agent-specific debugging per skill. Fix: The core SKILL.md in ~/.agents/skills/core/ MUST be agent-agnostic. Agent-specific content belongs in overrides/<agent>/SKILL.md. The core skill should never mention "Claude Code," "Copilot CLI," or any agent-specific feature. If a skill MUST reference agent-specific behavior, use conditional sections that the normalization pipeline renders per-agent.
PROCESS_TREE.md requirement creates a single point of failure for Claude Code skills. Claude Code (as of 2026-07) requires PROCESS_TREE.md in every skill directory for detection. If the automated PROCESS_TREE.md generation script fails, or a skill is manually added without running the generator, the skill is invisible to Claude Code — and only Claude Code. All other agents discover it via manifest or filesystem scan. The skill appears "deployed" but Claude Code users can't access it, and there's no error because Claude Code's silent-skip behavior means no log entry for missing PROCESS_TREE.md. Total cost: $5K-$15K in Claude Code-specific deployment failures. A missing PROCESS_TREE.md on 3 out of 30 skills means 10% of the skill fleet is invisible to Claude Code users. Each missing skill represents 20-40 hours of authoring effort that never reaches Claude Code. Fix: Generate PROCESS_TREE.md from skills-manifest.json as an automated build step. Add a CI check: for every skill in core/, verify PROCESS_TREE.md exists if claude-code is in the portability list. Monitor Claude Code issue #31005 for deprecation.
Relative path references in SKILL.md break when symlinks resolve to different locations. A skill at ~/.agents/skills/core/code-reviewer/SKILL.md references references/checklist.md. When symlinked to ~/.claude/skills/code-reviewer/SKILL.md, some agents resolve the symlink first (reading from the core path) while others read from the symlink location. Agents that read from the symlink location try to find ~/.claude/skills/code-reviewer/references/checklist.md — which doesn't exist because references/ is only at the core path. Total cost: $3K-$12K in broken reference debugging. References that work in one agent but 404 in another create "it works on my agent" support tickets. A skill with 8 reference files seeing 30% broken reference rate on 2 agents means 5 broken references × 2 agents = 10 manual fixes. Fix: Test reference link resolution on every target agent, not just the primary development agent. Use the symlink health check to verify all paths resolve. See references/symbolic-link-strategy.md for the full resolution guide.
Best Practices
Do use symlinks for cross-agent skill sharing, not copies — Copying skills to each agent's directory creates version drift within hours of the next update. A single symlink tree from ~/.agents/skills/core/ into each agent's skills directory ensures all agents load identical skill content atomically. Copy-based deployment costs 3-5 person-hours/month in drift reconciliation at $150/hour — $5,400-$9,000/year for a medium-sized skill library of 20-50 skills across 5+ agents.
Prefer manifest-driven discovery over directory scanning — Each agent implementing its own file-walk logic produces inconsistent skill availability: a skill that loads in Claude Code may silently fail in Copilot CLI because of different glob patterns or file filter rules. A skills-manifest.json with name, version, sha256, routing metadata, and invocation triggers provides O(1) guaranteed-consistent discovery. Manifest-driven discovery eliminates the "skill works in agent A but not agent B" class of bugs that costs 2-4 hours per incident to triage.
Always normalize frontmatter before publishing to any target agent — Vendor-specific frontmatter fields (cursorRules, geminiDirectives, codexOpenAPI, opencodeTOML) leak agent-specific configuration into other agents, causing parse errors or silent misbehavior. A normalization pipeline that strips vendor fields and validates against the portable spec spec prevents cross-agent contamination. One leaked vendor field can silently break skill loading on 3+ agents simultaneously — diagnosis requires checking each agent's logs individually.
Never deploy a skill without cross-agent compatibility testing on every target — Each agent terminal has unique quirks: YAML parsing differences, token budget interpretation, reference resolution behavior, and invocation pattern matching. A skill that passes tests in Claude Code may fail silently in Copilot CLI. Skipping compatibility testing means skills break in production on half the agent fleet — cost: $2K-$10K per broken deployment in triage, hotfix cycles, and lost productivity while skills are unavailable.
Measure manifest drift frequency as a health metric — Track how often skills-manifest.lock computed hashes diverge from the actual symlink tree contents. Drift >0% for more than 5 minutes after a skill update means your publishing pipeline has a race condition or incomplete update path. Undetected manifest drift causes "I updated the skill but the agent still uses old behavior" support tickets — each costs 30-60 minutes to diagnose. Alert on any drift within 5 minutes of a publish event.
Production Checklist
Before deploying or delivering work from this skill, verify:
#
Check
Verify
☐
Symlinks healthy across all agent directories: zero broken symlinks in any agent's skills directory
find ~/.claude/skills/ ~/.copilot/skills/ ~/.cursor/skills/ -type l ! -exec test -e {} \; -print returns empty
☐
Manifest current with zero drift: skills-manifest.lock SHA256 hashes match actual file tree hashes for every skill
`diff <(jq -r '.skills[]
☐
No vendor-specific field leakage: zero occurrences of agent-specific frontmatter fields in portable skill YAML
`grep -rE "cursorRules
☐
PROCESS_TREE.md present for every Claude Code skill operating in portability mode
`for d in ~/.agents/skills/core/*/; do test -f "$d/PROCESS_TREE.md"
☐
All reference links resolve: no broken internal links, missing reference files, or dangling cross-skill references
scripts/verify-skill.sh --check-references exits 0; no warnings about unresolved paths
☐
Compatibility test passes on every portability target agent: compatibility-report-*.json shows overall: "COMPATIBLE" for each declared agent
Verify report files for each agent (claude-code, copilot-cli, cursor, codex, gemini-cli); all show COMPATIBLE status
☐
Frontmatter validates per agent spec: normalization pipeline --validate-only flag passes on each target without errors
Run normalization with --validate-only per agent; zero validation errors; frontmatter conforms to each agent's expected schema
☐
Rollback plan is documented and tested
Manifest version history tracked in git; tested rollback to previous manifest version and verified all agents return to prior behavior; rollback time <2 minutes
Verification
Symlinks healthy: find ~/.claude/skills/ ~/.copilot/skills/ ~/.cursor/skills/ -type l ! -exec test -e {} \; -print returns empty (zero broken symlinks)
Manifest current: diff <(jq -r '.skills[] | "\(.name) \(.sha256)"' ~/.agents/skills/skills-manifest.lock) <(for d in ~/.agents/skills/core/*/; do name=$(basename "$d"); hash=$(find "$d" -type f -exec sha256sum {} \; | sort | sha256sum | cut -d' ' -f1); echo "$name $hash"; done) returns empty (no drift)
No vendor-specific leakage: grep -rE "cursorRules|geminiDirectives|codexOpenAPI|opencodeTOML" ~/.agents/skills/core/ returns empty
PROCESS_TREE.md present (if Claude Code in portability): for skill in ~/.agents/skills/core/*/; do test -f "$skill/PROCESS_TREE.md" || echo "MISSING: $skill"; done returns empty
All reference links resolve: scripts/verify-skill.sh passes reference link check
Compatibility test passes on all portability agents: compatibility-report-*.json shows overall: "COMPATIBLE" for every target agent
Frontmatter valid per agent: run normalization pipeline with --validate-only flag on each target agent
Verification Guardrails
Before delivering work, verify: self-check against What Good Looks Like, no broken references, continuity with State Log, no fabricated APIs/versions/capabilities, Error Recovery paths exercised, cross-skill dependencies satisfied. If any fail, revise before delivering.
