@givolt/i3-composer-agent 3.0.0 → 3.1.0

package/docs/skill-anatomy.md

@@ -0,0 +1,211 @@
+# Skill Anatomy
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+This document describes the structure and format of i3-composer-agent skill files. Use this as a guide when contributing new skills or understanding existing ones.
+
+## File Location
+
+Every skill lives in its own directory under `skills/`:
+
+```
+skills/
+  skill-name/
+    SKILL.md           # Required: The skill definition
+    scripts/           # Optional: Runnable helpers used by the skill workflow
+    references/        # Optional: Skill-specific reference documentation
+    supporting-file.md # Optional: Reference material loaded on demand
+```
+
+`SKILL.md` is the only required file. Add `scripts/` or `references/` only when the skill actually needs them, and omit them entirely for simpler skills.
+
+## SKILL.md Format
+
+### Frontmatter (Required)
+
+```yaml
+---
+name: skill-name-with-hyphens
+description: Guides agents through [task/workflow]. Use when [specific trigger conditions].
+---
+```
+
+**Rules:**
+- `name`: Lowercase, hyphen-separated. Must match the directory name.
+- `description`: Start with what the skill does in third person, then include one or more clear "Use when" trigger conditions. Include both *what* and *when*. Maximum 1024 characters.
+- Top-level keys are limited to the [Agent Skills specification](https://agentskills.io) fields: `name`, `description`, `license`, `compatibility`, `metadata`, and `allowed-tools`. Vendor or runtime controls such as `model`, `tools`, `max_turns`, or `context` go under `metadata` or in a per-agent adapter file; see [docs/advanced-per-agent-configuration.md](advanced-per-agent-configuration.md). The validator rejects any other top-level key.
+
+Published names are compatibility identifiers. In particular,
+`i3-browser-testing-with-devtools` is the stable upstream name because other
+skills refer to it directly. A downstream catalog may rename it, but that
+catalog owns the alias or migration mapping; downstream-only aliases are not
+maintained in this repository.
+
+**Why this matters:** Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill.
+
+### Standard Sections (Recommended Pattern)
+
+The frontmatter contract above is required. The section layout below is a recommended pattern, not a rigid template: equivalent headings are acceptable when they serve the same purpose clearly.
+
+```markdown
+# Skill Title
+
+## Overview
+One-two sentences explaining what this skill does and why it matters.
+
+## When to Use
+- Bullet list of triggering conditions (symptoms, task types)
+- When NOT to use (exclusions)
+
+## [Core Process / The Workflow / Steps]
+The main workflow, broken into numbered steps or phases.
+Include code examples where they help.
+Use flowcharts (ASCII) where decision points exist.
+
+## [Specific Techniques / Patterns]
+Detailed guidance for specific scenarios.
+Code examples, templates, configuration.
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| Excuse agents use to skip steps | Why the excuse is wrong |
+
+## Red Flags
+- Behavioral patterns indicating the skill is being violated
+- Things to watch for during review
+
+## Verification
+After completing the skill's process, confirm:
+- [ ] Checklist of exit criteria
+- [ ] Evidence requirements
+```
+
+## Section Purposes
+
+### Overview
+The "elevator pitch" for the skill. Should answer: What does this skill do, and why should an agent follow it?
+
+### When to Use
+Helps agents and humans decide if this skill applies to the current task. Include both positive triggers ("Use when X") and negative exclusions ("NOT for Y").
+
+### Core Process
+The heart of the skill. This is the step-by-step workflow the agent follows. Must be specific and actionable — not vague advice.
+
+**Good:** "Run `npm test` and verify all tests pass"
+**Bad:** "Make sure the tests work"
+
+### Common Rationalizations
+The most distinctive feature of well-crafted skills. These are excuses agents use to skip important steps, paired with rebuttals. They prevent the agent from rationalizing its way out of following the process.
+
+Think of every time an agent has said "I'll add tests later" or "This is simple enough to skip the spec" — those go here with a factual counter-argument.
+
+### Red Flags
+Observable signs that the skill is being violated. Useful during code review and self-monitoring.
+
+### Verification
+The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.).
+
+## Supporting Files
+
+Create supporting files only when:
+- Reference material exceeds 100 lines (keep the main SKILL.md focused)
+- Code tools or scripts are needed
+- Checklists are long enough to justify separate files
+
+Keep patterns and principles inline when under 50 lines.
+
+If a skill does not need runnable helpers, do not create an empty `scripts/` directory just to mirror other skills. Empty directories add noise without changing how the skill works.
+
+## Shared References
+
+Checklists used by more than one skill — testing, security, performance, accessibility, definition-of-done — live in `references/` at the repository root, deliberately *not* inside any skill directory.
+
+This is a pack-level design choice. The Agent Skills spec describes a skill as a self-contained directory, but several skills here point at the same checklists. Colocating those would force one of two options: copy the checklist into every skill that uses it, or pick one skill to "own" it and have the others reach into that directory. Both drift over time. A single repo-root copy stays the source of truth.
+
+The tradeoff is portability: a whole-repo install (such as the Claude Code marketplace plugin) carries `references/` along, but a per-skill install that copies only `skills/<name>/` leaves the repo-root sibling behind, and those links resolve to nothing. That gap is tracked in [upstream agent-skills #361](https://github.com/addyosmani/agent-skills/issues/361).
+
+Current convention: material used by exactly one skill is a supporting file inside that skill's directory; material shared across skills goes in `references/`.
+
+## Context Efficiency
+
+Skills load on demand: only the skill name and description sit in context at startup. The full `SKILL.md` loads only when an agent decides the skill is relevant. To keep that load cheap:
+
+- **Keep `SKILL.md` under 500 lines.** Move detailed reference material into supporting files.
+- **Write specific descriptions.** A precise description helps the agent activate the skill at the right moment and skip it otherwise.
+- **Use progressive disclosure.** Reference supporting files that are read only when the workflow reaches them.
+- **Prefer scripts over inline code.** Executing a script consumes no context; only its output does. Inline code blocks are paid for on every load.
+- **Keep file references one level deep.** Link directly from `SKILL.md` to supporting files rather than chaining through intermediate documents.
+
+## Script Requirements
+
+When a skill ships runnable helpers under `scripts/`, each script follows these conventions:
+
+- Use a `#!/bin/bash` shebang.
+- Use `set -e` for fail-fast behavior.
+- Write status messages to stderr: `echo "Message" >&2`.
+- Write machine-readable output (JSON) to stdout.
+- Include a cleanup trap for temporary files.
+- Reference the script path as `skills/<skill-name>/scripts/<script>.sh` (repo-relative).
+
+## Writing Principles
+
+1. **Process over knowledge.** Skills are workflows, not reference docs. Steps, not facts.
+2. **Specific over general.** "Run `npm test`" beats "verify the tests".
+3. **Evidence over assumption.** Every verification checkbox requires proof.
+4. **Anti-rationalization.** Every skip-worthy step needs a counter-argument in the rationalizations table.
+5. **Progressive disclosure.** Main SKILL.md is the entry point. Supporting files are loaded only when needed.
+6. **Token-conscious.** Every section must justify its inclusion. If removing it wouldn't change agent behavior, remove it.
+7. **Model-neutral.** Write the procedure, not the workaround. See [Write the Procedure, Not the Workaround](#write-the-procedure-not-the-workaround).
+
+## Write the Procedure, Not the Workaround
+
+Skills in this pack run on many agents and model generations. A step that exists because one model gets a specific call wrong is a liability on every other model: it constrains agents that would have solved the task directly, and it spends turns that stronger models need for the actual work. Cross-model transfer measurements ([WikiSkill, arXiv:2608.27454](https://arxiv.org/abs/2608.27454)) show skills authored against one model's execution failures can leave a stronger model performing *worse than with no skill at all*.
+
+**The rule:** if a step cannot be justified without naming a model, a model version, or one agent's private tool name, it belongs in an issue, not in a skill. Describe the capability ("run the focused test command", "write the file"), not the mechanism one runtime happens to expose (`run_command`, `write_to_file`).
+
+Two smells to check for before proposing skill content:
+
+- **Over-specified mechanics.** Prescribing an exact command form or serialization detail where stating the goal alone would do. If the justification is "model X gets this wrong otherwise", it's a workaround, not a procedure.
+- **Fragmented diagnostics.** A multi-step inspection sequence where one step would confirm the same thing. Every extra step spends turns, and turn budget is finite.
+
+This is about skill *content*; the portability of `references/` *paths* is a separate concern (see [Shared References](#shared-references)).
+
+## Naming Conventions
+
+- Skill directories: `lowercase-hyphen-separated`
+- Skill files: `SKILL.md` (always uppercase)
+- Supporting files: `lowercase-hyphen-separated.md`
+- Shared references: stored in the root `references/` directory, not inside skill directories (see [Shared References](#shared-references) for why).
+- Skill-specific references: a single supporting doc can stay as a loose file in the skill directory (the `Supporting files` entry above); when several related docs travel with the skill, the emerging convention for self-contained, distributable skills is to group them in a `references/` directory inside the skill directory, so the skill carries its own supporting docs.
+
+## Cross-Skill References
+
+Reference other skills by name:
+
+```markdown
+Follow the `i3-test-driven-development` skill for writing tests.
+If the build breaks, use the `i3-debugging-and-error-recovery` skill.
+```
+
+Don't duplicate content between skills — reference and link instead.
+
+## Required vs Recommended
+
+Required:
+
+- A `skills/<skill-name>/SKILL.md` file
+- Valid YAML frontmatter with `name` and `description`
+- A description that includes both what the skill does and when to use it
+
+Recommended:
+
+- The standard section flow shown above
+- Equivalent headings such as `How It Works`, `Core Process`, or `Workflow` when they read more naturally for the skill
+- Supporting files only when they keep the main `SKILL.md` focused

package/docs/upstream-repository/AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, Antigravity, etc.) when working with code in this repository.
+
+> **Scope:** This file configures agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself. It is not meant to be copied into other projects or into a global agent configuration; the reusable assets are the skills in `skills/`, not this file.
+
+## Repository Overview
+
+A collection of skills for Claude.ai and Claude Code for senior software engineers. Skills are packaged instructions and scripts that extend Claude and your coding agents capabilities.
+
+## OpenCode Integration
+
+OpenCode uses a **skill-driven execution model** powered by the `skill` tool and this repository's `/skills` directory.
+
+### Core Rules
+
+- If a task matches a skill, you MUST invoke it
+- Skills are located in `skills/<skill-name>/SKILL.md`
+- Never implement directly if a skill applies
+- Always follow the skill instructions exactly (do not partially apply them)
+
+### Intent → Skill Mapping
+
+The agent should automatically map user intent to skills:
+
+- Feature / new functionality → `spec-driven-development`, then `incremental-implementation`, `test-driven-development`
+- Planning / breakdown → `planning-and-task-breakdown`
+- Bug / failure / unexpected behavior → `debugging-and-error-recovery`
+- Code review → `code-review-and-quality`
+- Refactoring / simplification → `code-simplification`
+- API or interface design → `api-and-interface-design`
+- UI work → `frontend-ui-engineering`
+
+### Lifecycle Mapping (Implicit Commands)
+
+OpenCode does not support slash commands like `/spec` or `/plan`.
+
+Instead, the agent must internally follow this lifecycle:
+
+- DEFINE → `spec-driven-development`
+- PLAN → `planning-and-task-breakdown`
+- BUILD → `incremental-implementation` + `test-driven-development`
+- VERIFY → `debugging-and-error-recovery`
+- REVIEW → `code-review-and-quality`
+- SHIP → `shipping-and-launch`
+
+### Execution Model
+
+For every request:
+
+1. Determine if any skill applies (even 1% chance)
+2. Invoke the appropriate skill using the `skill` tool
+3. Follow the skill workflow strictly
+4. Only proceed to implementation after required steps (spec, plan, etc.) are complete
+
+### Anti-Rationalization
+
+The following thoughts are incorrect and must be ignored:
+
+- "This is too small for a skill"
+- "I can just quickly implement this"
+- "I’ll gather context first"
+
+Correct behavior:
+
+- Always check for and use skills first
+
+This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.
+
+## Orchestration: Personas, Skills, and Commands
+
+This repo has three composable layers. They have different jobs and should not be confused:
+
+- **Skills** (`skills/<name>/SKILL.md`) — workflows with steps and exit criteria. The *how*. Mandatory hops when an intent matches.
+- **Personas** (`agents/<role>.md`) — roles with a perspective and an output format. The *who*.
+- **Slash commands** (`.claude/commands/*.md`) — user-facing entry points. The *when*. The orchestration layer.
+
+Composition rule: **the user (or a slash command) is the orchestrator. Personas do not invoke other personas.** A persona may invoke skills.
+
+The only multi-persona orchestration pattern this repo endorses is **parallel fan-out with a merge step** — used by `/ship` to run `code-reviewer`, `security-auditor`, and `test-engineer` concurrently and synthesize their reports. Do not build a "router" persona that decides which other persona to call; that's the job of slash commands and intent mapping.
+
+See [docs/agents.md](docs/agents.md) for the decision matrix and [references/orchestration-patterns.md](references/orchestration-patterns.md) for the full pattern catalog.
+
+**Claude Code interop:** the personas in `agents/` work as Claude Code subagents (auto-discovered from this plugin's `agents/` directory) and as Agent Teams teammates (referenced by name when spawning). Two platform constraints align with our rules: subagents cannot spawn other subagents, and teams cannot nest. Plugin agents silently ignore the `hooks`, `mcpServers`, and `permissionMode` frontmatter fields.
+
+## Creating a New Skill
+
+> **Before you start:** run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill), search the catalog, check open PRs (`gh pr list --state open`), confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap in your PR description. Most new-skill ideas overlap an existing skill or an open PR; prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow.
+
+Skills in this repo are markdown-first: each lives at `skills/<kebab-case-name>/SKILL.md` with YAML frontmatter (`name`, `description`) and follows the section anatomy (Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification). Add a `scripts/` directory only when the skill ships runnable helpers; most skills are markdown only, and there are no per-skill zip packages.
+
+For the full format, naming conventions, frontmatter rules, supporting-file thresholds, and writing principles, see [docs/skill-anatomy.md](docs/skill-anatomy.md), the single source of truth for skill structure. Do not restate that guidance here, link to it.

package/docs/upstream-repository/CLAUDE.md

@@ -0,0 +1,60 @@
+# agent-skills
+
+This is the agent-skills project — a collection of production-grade engineering skills for AI coding agents.
+
+> **Scope:** This file configures agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself, not other projects. Don't copy it into another project or a global agent configuration; the reusable assets are the skills in `skills/`.
+
+## Project Structure
+
+```
+skills/       → Core skills (SKILL.md per directory)
+agents/       → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor)
+hooks/        → Session lifecycle hooks
+.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit)
+references/   → Supplementary checklists (testing, performance, security, accessibility, observability)
+evals/        → Skill eval cases + framework (see evals/README.md)
+docs/         → Setup guides for different tools
+```
+
+## Skills by Phase
+
+**Define:** interview-me, idea-refine, spec-driven-development
+**Plan:** planning-and-task-breakdown
+**Build:** incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design
+**Verify:** browser-testing-with-devtools, debugging-and-error-recovery
+**Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
+**Ship:** git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, shipping-and-launch
+
+## Conventions
+
+- Every skill lives in `skills/<name>/SKILL.md`
+- YAML frontmatter with `name` and `description` fields
+- Description starts with what the skill does (third person), followed by trigger conditions ("Use when...")
+- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
+- Shared references are in the root `references/` directory; the emerging convention for self-contained, distributable skills keeps a skill's own references inside `skills/<name>/references/`
+- Supporting files only created when content exceeds 100 lines
+
+## Contributing
+
+Before adding a new skill or significantly reworking an existing one, run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs, confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap. Prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow; do not restate its checklist here or elsewhere, link to it.
+
+## Commands
+
+- `npm test` — Not applicable (this is a documentation project)
+- Validate: Check that all SKILL.md files have valid YAML frontmatter with name and description
+- Evals: `node scripts/run-evals.js` — trigger/routing evals for every skill (CI); `--behavioral <skill>` for graded runs
+
+## Pull Requests
+
+PRs target the upstream repository's default branch. In a typical fork setup the upstream remote is `upstream` and your fork is `origin`, but the exact remote names are not what matters here.
+
+- Before opening a PR, search the upstream repository's open PRs and issues for work that touches the same files or rules. If any overlaps, coordinate (build on it, align your rules with it, or rebase after it merges) instead of opening a conflicting PR.
+- Prefer small, focused PRs over large refactors of widely shared files (for example, files under `scripts/`), which are more likely to collide with in-flight work.
+
+## Boundaries
+
+- Always: Run the CONTRIBUTING.md pre-flight checks before creating a new skill directory
+- Always: Follow the skill-anatomy.md format for new skills
+- Always: Check the upstream repo's open PRs and issues for overlap before opening a new PR
+- Never: Add skills that are vague advice instead of actionable processes
+- Never: Duplicate content between skills — reference other skills instead

package/docs/upstream-repository/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing to Agent Skills
+
+Thanks for your interest in contributing! This project is a collection of production-grade engineering skills for AI coding agents.
+
+New here? [docs/developer-onboarding.md](docs/developer-onboarding.md) is a guided tour of how the repo fits together (the five layers, the verification loop, and the contribution paths) and tells you when to read this document, [skill-anatomy.md](docs/skill-anatomy.md), and [evals/README.md](evals/README.md). This file is the authoritative rulebook; the onboarding guide is the map.
+
+## Adding a New Skill
+
+### Before proposing a new skill
+
+This pack already covers most of the development lifecycle, and many proposals overlap with an existing skill or another open PR. Before opening one, do these checks so reviewers aren't triaging duplicates:
+
+1. **Search the catalog.** Browse [the skill list in the README](README.md) and skim `skills/` for an existing skill that covers your idea, whole or in part.
+2. **Check open PRs.** Run `gh pr list --state open` (or browse the PRs tab) and look for proposals on the same topic. Clusters of near-duplicate skills already exist; don't add to them.
+3. **Check rejected proposals.** Search the [skill-change rejection ledger](evals/skill-impact.md) for earlier proposals that overlap with your idea and review their eval evidence before repeating the work.
+4. **Read the anatomy.** Confirm your idea fits the format in [docs/skill-anatomy.md](docs/skill-anatomy.md), an actionable workflow with verification, not vague advice.
+5. **Justify the gap in your PR description.** State explicitly why this isn't covered by an existing skill, open PR, or previously rejected proposal. If it overlaps, propose extending the existing skill instead of adding a new one.
+6. **Strip model-specific workarounds.** If a step can't be justified without naming a model, a model version, or one agent's private tool name, it doesn't belong in a skill — describe the capability instead (see [Write the Procedure, Not the Workaround](docs/skill-anatomy.md#write-the-procedure-not-the-workaround)).
+
+If your idea is a refinement of an existing skill, prefer a focused edit to that skill over a new directory.
+
+### Creating the skill
+
+1. Create a directory under `skills/` with a kebab-case name
+2. Add a `SKILL.md` following the format in [docs/skill-anatomy.md](docs/skill-anatomy.md)
+3. Include YAML frontmatter with `name` and `description` fields, and no vendor or runtime keys at the top level (those go under `metadata` or in a per-agent adapter file; see [docs/advanced-per-agent-configuration.md](docs/advanced-per-agent-configuration.md))
+4. Ensure the `description` starts with what the skill does (third person), then includes one or more `Use when` trigger conditions
+
+### Skill Quality Bar
+
+Skills should be:
+
+- **Specific** — Actionable steps, not vague advice
+- **Verifiable** — Clear exit criteria with evidence requirements
+- **Battle-tested** — Based on real engineering workflows, not theoretical ideals
+- **Minimal** — Only the content needed to guide the agent correctly
+
+### Structure
+
+Every new skill must have:
+
+- `SKILL.md` in the skill directory
+- YAML frontmatter with valid `name` and `description`
+- An eval case file at `evals/cases/<skill-name>.json` — at least 3 positive triggers, 2 negative triggers (with `owner` where possible), and 1 behavioral eval. Execution evals must be backed by real files under `evals/fixtures/`; conversation-shaped skills may use a reviewer-gated `kind: "dialogue"` eval instead (see [evals/README.md](evals/README.md)). CI enforces these requirements.
+
+New skills should generally follow the standard anatomy:
+
+- **Overview** — What this skill does and why it matters
+- **When to Use** — Triggering conditions
+- **Process** — Step-by-step workflow
+- **Common Rationalizations** — Excuses agents use to skip steps, with rebuttals
+- **Red Flags** — Warning signs that the skill is being applied incorrectly
+- **Verification** — How to confirm the skill was applied correctly
+
+The frontmatter fields above are required. The section anatomy is a recommended pattern: equivalent headings such as `How It Works`, `Workflow`, or `Core Process` are fine when they preserve the same intent and keep the skill easy to follow.
+
+### What Not to Do
+
+- Don't duplicate content between skills — reference other skills instead
+- Don't add skills that are vague advice instead of actionable processes
+- Don't create supporting files unless content exceeds 100 lines
+- Don't create an empty `scripts/` directory just to match another skill — add `scripts/` only when the skill includes runnable helpers
+- Don't put reference material inside skill directories — use `references/` instead
+
+## Modifying Existing Skills
+
+Before proposing a change, search the [skill-change rejection ledger](evals/skill-impact.md) for previous attempts affecting the same skill and review their eval evidence.
+
+- Keep changes focused and minimal
+- Preserve the existing structure and tone
+- Test that YAML frontmatter remains valid after edits
+
+If a skill or description change is rejected based on eval results, add one row to the ledger with the date, affected skill, concise attempted change, before-to-after rank-1 score, and rejected PR link and outcome. Land that ledger-only update separately on the default branch; do not leave it only on the rejected proposal branch, where closing or force-pushing the proposal could discard the record.
+
+## Adding a Host Guide
+
+The README install section lists only hosts a maintainer has installed and run the current release on. Every other host gets one line in [docs/other-hosts.md](docs/other-hosts.md): the host name and its install command. No dedicated setup page, vendor links, logos, emoji, or screenshots.
+
+- If you work for the company behind the host, say so in the PR.
+- A host moves into the README once a maintainer has run it and is willing to keep its entry current.
+- Host guides are reviewed in the order they were opened.
+
+## Repo-scoped files
+
+`AGENTS.md` and `CLAUDE.md` at the repo root configure agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself. When writing setup guides or docs, do not instruct users to copy these files into their own projects or into a global agent configuration; the reusable assets are the skills in `skills/`.
+
+## Translations
+
+We don't accept translations of the documentation (README, `docs/`) or of skills and their content. Translated copies drift out of sync as skills and docs evolve, and we have no way to maintain them long-term without leaning on agent translations plus community corrections, which adds maintenance cost for limited value. Keep all skills, docs, and contributions in English.
+
+## Testing Hooks
+
+The session-start script (`hooks/session-start.sh`) injects the `using-agent-skills` meta-skill when wired into a host's `SessionStart` hook. The Claude Code plugin does not register it — Claude Code routes skills natively, and always-on injection would create two routers for the same task (see [docs/getting-started.md](docs/getting-started.md)); the script remains for hosts without native skill routing. A regression test at `hooks/session-start-test.sh` validates the script's JSON payload — both when `jq` is available and when it isn't.
+
+Run it before opening any PR that touches:
+
+- `hooks/session-start.sh`
+- `skills/using-agent-skills/SKILL.md` (the meta-skill content embedded by the hook)
+
+```bash
+bash hooks/session-start-test.sh
+```
+
+Expected output: `session-start JSON payload OK`. The script exits non-zero on any assertion failure.
+
+### Reproducing the no-jq fallback
+
+The hook still emits the same `hookSpecificOutput` envelope when `jq` isn't on `PATH`, with `additionalContext` explaining that `jq` is required. To exercise that branch locally, strip `jq`'s directory from `PATH` for the test invocation:
+
+```bash
+JQ_DIR=$(dirname "$(command -v jq)")
+PATH=$(echo "$PATH" | tr ':' '\n' | grep -v "^${JQ_DIR}$" | tr '\n' ':' | sed 's/:$//') \
+  bash hooks/session-start-test.sh
+```
+
+This works cleanly when `jq` lives in its own directory (e.g. `/opt/homebrew/bin` from Homebrew, `/usr/local/bin` from a manual install). If your `jq` shares a system bin with other tools the test depends on (such as `mktemp` in `/usr/bin`), the simpler approach is to install `jq` via a separate package manager so it has its own bin directory, then re-run.
+
+The hook's `command -v jq` check fails under the stripped `PATH`, the jq-missing fallback runs, and the test asserts the `jq is required` guidance in `additionalContext` instead of the meta-skill body.
+
+## Reporting Issues
+
+Open an issue if you find:
+
+- A skill that gives incorrect or outdated guidance
+- Missing coverage for a common engineering workflow
+- Inconsistencies between skills
+
+If a skill's guidance was wrong, outdated, or did not apply in your project
+(for example, it assumed `npm test` in a Maven or Gradle repo), use the
+[Skill gap](https://github.com/addyosmani/agent-skills/issues/new?template=skill-gap.yml)
+issue form. It asks for the affected skill, the relevant excerpt, your project
+context, and what you did instead — enough for maintainers to triage without a
+freeform write-up.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/docs/upstream-repository/README.md

@@ -0,0 +1,8 @@
+# 上游原版仓库资料
+
+来源：addyosmani/agent-skills，固定提交 aeac41d4d005999432bb7312f7ff06383a91d59d。
+
+本目录保留原版仓库规则、贡献资料和配置的完整原文字节，供阅读和恢复；不会注册为业务项目或宿主的活动规则。
+文件对应关系、原始路径、Git 模式和摘要见 manifest.json。gitignore.txt、gitattributes.txt 使用可随包交付的文件名。
+opencode-skills.link 保存原链接目标 ../skills/，manifest.json 保留其 120000 模式；这是可恢复的链接表示，实际技能发现继续使用所选宿主的登记。
+此处的命令、路径和文档链接保留上游语境，需结合完整上游仓库阅读；不把它们当成本项目的执行指令。

package/docs/upstream-repository/gitattributes.txt

@@ -0,0 +1 @@
+* text=auto eol=lf

package/docs/upstream-repository/gitignore.txt

@@ -0,0 +1,10 @@
+.DS_Store
+node_modules/
+.env
+.env.*
+*.log
+.claude/.simplify-ignore-cache/
+.claude/sdd-cache/
+evals/results/
+evals/plugin/results/
+__pycache__/

package/docs/upstream-repository/manifest.json

@@ -0,0 +1,71 @@
+{
+  "schemaVersion": 1,
+  "upstreamCommit": "aeac41d4d005999432bb7312f7ff06383a91d59d",
+  "files": [
+    {
+      "path": "AGENTS.md",
+      "preservedPath": "docs/upstream-repository/AGENTS.md",
+      "mode": "100644",
+      "blob": "e97670ed868e90b73753fafbe305cdabc7f55ad3",
+      "sha256": "a12bac68c447f8043a75c2259175b36a57a37617a5ab92900ab1e3e9afa381be"
+    },
+    {
+      "path": "CLAUDE.md",
+      "preservedPath": "docs/upstream-repository/CLAUDE.md",
+      "mode": "100644",
+      "blob": "97674d0b173c7c25764e11dc816a298a63119594",
+      "sha256": "f03b7aaf2c08ab93e70a020442634a09f518286ff1beb7b8353dde92533ff9b0"
+    },
+    {
+      "path": "CONTRIBUTING.md",
+      "preservedPath": "docs/upstream-repository/CONTRIBUTING.md",
+      "mode": "100644",
+      "blob": "3c3a015be673a04efd8647c201acfbb2fad7189a",
+      "sha256": "fe5d17011565e9cfeb8a02510c81a243f3e4d829b800e2eab239039fcac214e7"
+    },
+    {
+      "path": ".gitattributes",
+      "preservedPath": "docs/upstream-repository/gitattributes.txt",
+      "mode": "100644",
+      "blob": "6313b56c57848efce05faa7aa7e901ccfc2886ea",
+      "sha256": "d60f352d0db1404c70afb4bb8b2ca3fd1c610572aa40720e8a0b7baa7885418c"
+    },
+    {
+      "path": ".gitignore",
+      "preservedPath": "docs/upstream-repository/gitignore.txt",
+      "mode": "100644",
+      "blob": "167e5ad35e10c75795667a7b71c950eda641cdd8",
+      "sha256": "09bc8ca679551d8d723abeaadf303f3dcdaf93b94d0ad211873942a47c8559a2"
+    },
+    {
+      "path": ".claude/rules/skills-contributing.md",
+      "preservedPath": "docs/upstream-repository/skills-contributing.md",
+      "mode": "100644",
+      "blob": "8553dc3b0d4aba42f014605b488097b6e06e9060",
+      "sha256": "6f8ff659388c3b957322ac46f788ff16d996e5c751f71a6c1e59e4761c437bbd"
+    },
+    {
+      "path": ".github/ISSUE_TEMPLATE/skill-gap.yml",
+      "preservedPath": "docs/upstream-repository/skill-gap.yml",
+      "mode": "100644",
+      "blob": "dac6216a5ace3cd1f34bb2b9a753c6f133592892",
+      "sha256": "f6a7748bfe8a1a43c42c7a5e7317c66689b66afd514ee091eb6f8ce07e46d5a4"
+    },
+    {
+      "path": ".github/workflows/test-plugin-install.yml",
+      "preservedPath": "docs/upstream-repository/test-plugin-install.yml",
+      "mode": "100644",
+      "blob": "b25ba319a8d371c6c1924f8b75173bb319313ab2",
+      "sha256": "fe1437efbdd99bd9ea1fa2bf79aa921f8bdd68a067802e4b41af531a3aa39597"
+    },
+    {
+      "path": ".opencode/skills",
+      "preservedPath": "docs/upstream-repository/opencode-skills.link",
+      "mode": "120000",
+      "blob": "7fc7d9f7be858ee62e454c529b3f8deddd83e1d2",
+      "sha256": "9d36d6a253d6844eb107d26dc0dcd8252808449433b251eceb14cee3517a185a",
+      "target": "../skills/",
+      "representation": "serialized-symlink"
+    }
+  ]
+}

package/docs/upstream-repository/opencode-skills.link

@@ -0,0 +1 @@
+../skills/