@anionzo/skill 1.1.0

package/scripts/validate-skills

@@ -0,0 +1,103 @@
+#!/usr/bin/env sh
+
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+FAIL=0
+WARN=0
+
+require_file() {
+  if [ ! -f "$1" ]; then
+    printf 'Missing file: %s\n' "$1" >&2
+    FAIL=1
+  fi
+}
+
+require_dir() {
+  if [ ! -d "$1" ]; then
+    printf 'Missing directory: %s\n' "$1" >&2
+    FAIL=1
+  fi
+}
+
+require_key() {
+  file=$1
+  key=$2
+
+  if [ ! -f "$file" ]; then
+    return
+  fi
+
+  if ! grep -Eq "^${key}:[[:space:]]*" "$file"; then
+    printf 'Missing key %s in %s\n' "$key" "$file" >&2
+    FAIL=1
+  fi
+}
+
+warn_key() {
+  file=$1
+  key=$2
+
+  if [ ! -f "$file" ]; then
+    return
+  fi
+
+  if ! grep -Eq "^${key}:[[:space:]]*" "$file"; then
+    printf 'WARN: Missing key %s in %s\n' "$key" "$file" >&2
+    WARN=1
+  fi
+}
+
+warn_empty_dir() {
+  dir=$1
+  label=$2
+
+  if [ -d "$dir" ]; then
+    if [ -z "$(ls -A "$dir" 2>/dev/null)" ]; then
+      printf 'WARN: %s is empty\n' "$label" >&2
+      WARN=1
+    fi
+  fi
+}
+
+require_dir "$ROOT/docs"
+require_dir "$ROOT/skills"
+require_dir "$ROOT/knowledge"
+require_dir "$ROOT/templates"
+require_dir "$ROOT/adapters"
+require_dir "$ROOT/scripts"
+
+for layer in global project working; do
+  require_dir "$ROOT/knowledge/$layer"
+done
+
+for skill_dir in "$ROOT"/skills/*; do
+  [ -d "$skill_dir" ] || continue
+
+  require_file "$skill_dir/meta.yaml"
+  require_file "$skill_dir/SKILL.md"
+  require_file "$skill_dir/examples.md"
+  require_dir "$skill_dir/references"
+
+  require_key "$skill_dir/meta.yaml" "name"
+  require_key "$skill_dir/meta.yaml" "version"
+  require_key "$skill_dir/meta.yaml" "category"
+  require_key "$skill_dir/meta.yaml" "summary"
+
+  warn_key "$skill_dir/meta.yaml" "summary_vi"
+  warn_key "$skill_dir/meta.yaml" "triggers"
+  warn_key "$skill_dir/meta.yaml" "related_skills"
+
+  warn_empty_dir "$skill_dir/references" "$skill_dir/references"
+done
+
+if [ "$WARN" -ne 0 ]; then
+  printf '\nWarnings found.\n' >&2
+fi
+
+if [ "$FAIL" -ne 0 ]; then
+  printf 'Skill library validation failed.\n' >&2
+  exit 1
+fi
+
+printf 'Skill library validation passed.\n'

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,45 @@
+# Brainstorming
+
+## Purpose
+
+Refine a fuzzy request into a concrete direction that is clear enough to plan.
+
+## When To Use
+
+Load this skill when:
+
+- the user has an idea but not a settled approach
+- the scope or success criteria are still unclear
+- multiple reasonable options exist and the tradeoff matters
+- starting implementation immediately would force too many assumptions
+
+Skip this skill and go directly to `planning` when the request is already specific: a named feature with clear scope, a known code path, or an explicit task with acceptance criteria.
+
+## Workflow
+
+1. Restate the request in plain language.
+2. Ask focused questions that reduce ambiguity quickly.
+3. Surface the most important tradeoffs, not every possible one.
+4. Propose one or two viable directions with clear consequences.
+5. Lock the current best direction, scope boundary, and open questions.
+6. End with a handoff into `planning` when the request is concrete enough.
+
+## Output Format
+
+- clarified goal
+- constraints and assumptions
+- viable options considered
+- recommended direction
+- unresolved questions
+- next skill to invoke
+
+## Red Flags
+
+- diving into file-level implementation too early
+- asking many questions that do not change the decision
+- presenting vague options with no tradeoff explanation
+- pretending the problem is settled when key constraints are still unknown
+
+## Done Criteria
+
+This skill is complete when all three of the following are written down explicitly: the recommended direction, at least one key constraint, and the scope boundary. At that point, `planning` can proceed without inventing missing requirements.

package/skills/brainstorming/examples.md

@@ -0,0 +1,61 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+I want better auth in the admin area.
+```
+
+Expected result:
+
+- clarify whether this means SSO, MFA, RBAC changes, or session hardening
+- identify the real goal and constraints
+- end with a chosen direction that can be planned
+
+## Example 2
+
+User request:
+
+```text
+Help me think through how we should add an audit log.
+```
+
+Expected result:
+
+- narrow the audit scope, retention, and actor model
+- compare one or two realistic approaches
+- hand off to planning once the direction is concrete
+
+## Example 3 — Sample completed output
+
+User request:
+
+```text
+I want better auth in the admin area.
+```
+
+### Completed output
+
+```
+Clarified goal: Strengthen authentication for the admin panel to reduce unauthorized access risk.
+
+Constraints and assumptions:
+- Admin panel is a React SPA; auth goes through the existing session cookie flow.
+- No budget for a third-party IdP at this stage.
+- Must not break the existing user login flow.
+
+Viable options considered:
+1. Add MFA via TOTP — moderate effort, strong security gain.
+2. Add IP allowlist — low effort, but brittle for remote teams.
+3. Replace session cookies with short-lived JWTs — high effort, marginal gain for this use case.
+
+Recommended direction: Add TOTP-based MFA for admin users only. It provides the highest security gain within the current architecture without requiring external services.
+
+Unresolved questions:
+- Should MFA be mandatory or opt-in at first?
+- Recovery flow: backup codes or email fallback?
+
+Next skill: planning
+```

package/skills/brainstorming/meta.yaml

@@ -0,0 +1,23 @@
+name: brainstorming
+version: 0.1.0
+category: discovery
+summary: Turn a rough idea or underspecified request into a concrete, reviewable direction before planning begins.
+summary_vi: Biến ý tưởng thô hoặc request chưa rõ thành hướng đi cụ thể, có thể review, trước khi bắt đầu lập plan.
+triggers:
+  - help me think this through
+  - explore the approach first
+  - the request is vague or underspecified
+inputs:
+  - rough idea
+  - user goals and constraints
+outputs:
+  - clarified goal
+  - key decisions
+  - open questions
+  - handoff into planning
+constraints:
+  - avoid jumping into code or low-level implementation too early
+  - keep the discussion concrete and decision-oriented
+related_skills:
+  - using-skills
+  - planning

package/skills/brainstorming/references/output-template.md

@@ -0,0 +1,26 @@
+## Clarified Goal
+
+- What the user is actually trying to achieve
+
+## Constraints
+
+- Required constraints:
+- Assumptions:
+
+## Options
+
+1. Option one and its tradeoff
+2. Option two and its tradeoff
+
+## Recommended Direction
+
+- Chosen direction:
+- Why:
+
+## Open Questions
+
+- Remaining unresolved item
+
+## Handoff
+
+- Next skill to invoke:

package/skills/bug-triage/SKILL.md

@@ -0,0 +1,47 @@
+# Bug Triage
+
+## Purpose
+
+Investigate failures methodically so the next fix is based on evidence instead of guesswork.
+
+## When To Use
+
+Load this skill when:
+
+- a user reports a bug or regression
+- a test starts failing without obvious cause
+- production behavior no longer matches the intended behavior
+
+## Workflow
+
+1. Restate the symptom in plain language.
+2. Attempt to reproduce the issue or explain why reproduction is blocked.
+3. Narrow the problem:
+   - identify the code path involved
+   - inspect recent behavior changes or assumptions
+   - check inputs, state, timing, or environment differences
+4. Form the smallest credible root-cause hypothesis.
+5. Define the minimal next change or experiment that would confirm the cause.
+6. Add or recommend regression coverage when the cause is clear.
+
+## Output Format
+
+- symptom summary
+- reproduction status
+- suspected root cause
+- impacted area
+- proposed next change
+- confidence level
+
+## Red Flags
+
+- proposing a rewrite before understanding the current failure
+- changing many files before narrowing the cause
+- ignoring whether the behavior is reproducible
+- treating logs or stack traces as proof without checking the code path
+
+## Done Criteria
+
+This skill is complete when the next fix or experiment is specific, minimal, and tied to a clearly stated hypothesis.
+
+If the fix is non-trivial or touches more than one area, hand off to `planning` before moving to `feature-delivery`.

package/skills/bug-triage/examples.md

@@ -0,0 +1,68 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Users get logged out randomly after the deploy.
+```
+
+Expected result:
+
+- restate the symptom and affected surface area
+- inspect auth session code path and recent deploy changes
+- identify one or two likely causes before editing unrelated modules
+
+Sample completed output:
+
+```
+Symptom: Users with active sessions are being logged out unexpectedly after the v2.4.1 deploy.
+
+Reproduction: Confirmed on staging — session is invalidated ~10 minutes after login even without user action.
+
+Root-Cause Hypothesis:
+- Most likely: SESSION_TTL env var was changed from 3600 to 600 in the deploy config
+- Evidence: session.ts reads process.env.SESSION_TTL; config diff shows the change
+- Uncertainty: not yet confirmed whether all env changes were intentional
+
+Next Change: Restore SESSION_TTL to 3600 in production config and redeploy
+
+Confidence: high
+
+Handoff: feature-delivery (fix is already clear and local)
+```
+
+## Example 2
+
+User request:
+
+```text
+This integration test started failing with a timeout.
+```
+
+Expected result:
+
+- determine where the timeout occurs
+- distinguish between slow setup, deadlock, or missing response
+- propose the smallest confirming step
+
+### Completed output
+
+```
+Symptom: Integration test `test/integration/payment.test.ts` times out after 30s on the "processes valid refund" case.
+
+Reproduction: Confirmed locally — `npm test -- payment` hangs at step 3/5 of the refund flow test.
+
+Root-Cause Hypothesis:
+- Most likely: The mock payment gateway is not responding to the refund callback, causing the test to wait indefinitely
+- Evidence: The test uses a mock server on port 9999; logs show the request is sent but no response is received
+- Alternative: A database connection pool exhaustion from a previous test not cleaning up properly
+- Uncertainty: need to check if the mock server is started before the refund call
+
+Confirming Step: Add a 5s timeout to the mock refund endpoint and log whether it receives the request. If the mock receives it but doesn't respond, the mock handler is missing the refund route.
+
+Confidence: medium
+
+Handoff: planning (once root cause is confirmed, the fix is likely a one-line mock handler addition)
+```

package/skills/bug-triage/meta.yaml

@@ -0,0 +1,25 @@
+name: bug-triage
+version: 0.1.0
+category: debugging
+summary: Turn a bug report or failure symptom into a grounded root-cause hypothesis and a minimal next fix.
+summary_vi: Biến bug report hoặc triệu chứng lỗi thành giả thuyết nguyên nhân gốc có căn cứ và bước sửa tối thiểu tiếp theo.
+triggers:
+  - investigate this error
+  - debug this regression
+  - failing test or production issue
+inputs:
+  - bug report
+  - logs or stack traces when available
+  - code paths involved in the failure
+outputs:
+  - reproduction status
+  - root-cause hypothesis
+  - minimal next change
+constraints:
+  - prove or narrow the cause before broad refactors
+  - call out confidence and uncertainty explicitly
+related_skills:
+  - using-skills
+  - planning
+  - feature-delivery
+  - verification-before-completion

package/skills/bug-triage/references/output-template.md

@@ -0,0 +1,26 @@
+## Symptom
+
+- What is failing and how it shows up
+
+## Reproduction
+
+- reproduced: yes or no
+- notes:
+
+## Root-Cause Hypothesis
+
+- most likely cause:
+- evidence:
+- uncertainty:
+
+## Next Change
+
+- smallest fix or confirming experiment
+
+## Confidence
+
+- low, medium, or high
+
+## Handoff
+
+- Next skill: planning (if fix is non-trivial) or feature-delivery (if fix is already clear)

package/skills/code-review/SKILL.md

@@ -0,0 +1,41 @@
+# Code Review
+
+## Purpose
+
+Review code changes with a risk-first mindset.
+
+## When To Use
+
+Load this skill when the user asks for a review of a diff, PR, commit range, or changed files.
+
+## Workflow
+
+1. Inspect the full set of relevant changes.
+2. Identify behavior changes and impacted code paths.
+3. Look for:
+   - correctness bugs
+   - regressions
+   - missing validation or edge-case handling
+   - missing or misleading tests
+4. Return findings ordered by severity, with file references.
+5. Keep summaries brief and put them after the findings.
+
+## Output Format
+
+- findings first, ordered by severity
+- file and line references when available
+- open questions or assumptions
+- short summary or residual risk note
+
+## Red Flags
+
+- reviewing only the latest file and ignoring related changes
+- focusing on style before correctness
+- vague comments with no user-visible impact
+- claiming safety without considering missing tests or migration risk
+
+## Done Criteria
+
+This skill is complete when every finding includes a severity, a file and line reference where possible, and a plain-language statement of user-visible impact. The residual risk field must be populated even if no blocking issues were found.
+
+If blocking issues are found, hand off to `bug-triage` or `planning` before the change proceeds.

package/skills/code-review/examples.md

@@ -0,0 +1,77 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Please review this auth refactor.
+```
+
+Expected result:
+
+- inspect all changed auth paths
+- identify any behavior regressions or missing tests
+- report findings before giving a summary
+
+Sample completed output:
+
+```
+Findings:
+
+1. [blocking] src/auth/session.ts:47 — The old token rotation logic has been removed.
+   Existing sessions from before the deploy will have tokens that no longer validate.
+   This will silently log out all active users on deploy.
+
+2. [major] src/auth/middleware.ts:112 — The JWT expiry check now uses Date.now() instead
+   of the previous clock-skew-tolerant comparison. Tokens issued within 5 seconds of
+   expiry may be wrongly rejected under load.
+
+3. [minor] src/auth/local.ts:88 — The error message on failed login now leaks whether
+   the email exists. Previously it returned a generic message.
+
+Open Questions:
+- Was token rotation intentionally removed? If yes, existing sessions need to be
+  invalidated before deploy.
+
+Residual Risk: If finding 1 is acknowledged and existing sessions are cleared before
+deploy, the remaining issues are manageable. Blocking on finding 1.
+
+Handoff: planning (finding 1 requires a migration step before shipping)
+```
+
+## Example 2
+
+User request:
+
+```text
+Review this PR like a senior engineer.
+```
+
+Expected result:
+
+- focus on bugs, risks, and rollout issues
+- avoid spending most of the review on style comments
+
+### Completed output
+
+```
+Findings:
+
+1. [major] src/api/users.ts:34 — The pagination offset is parsed with parseInt() but has no validation for negative values.
+   A client sending `?offset=-1` would cause an out-of-bounds database query. Should clamp to 0 or reject.
+
+2. [minor] src/utils/format.ts:12 — The date formatter uses the local timezone instead of UTC.
+   This could cause inconsistent dates for users in different timezones. Existing API docs specify UTC.
+
+3. [info] Package.json adds 3 new dependencies. Two are well-known (lodash, date-fns), but `tiny-logger` has only 12 GitHub stars and no published security audit.
+   Worth verifying before merging.
+
+Open Questions:
+- Was the offset validation intentionally deferred? If so, it should be tracked as a follow-up ticket.
+- Is the timezone change intentional or an oversight?
+
+Residual Risk: Finding 1 could cause runtime errors under adversarial input. Should be fixed before merge.
+
+Handoff: feature-delivery (fix offset validation before merging)
+```

package/skills/code-review/meta.yaml

@@ -0,0 +1,24 @@
+name: code-review
+version: 0.1.0
+category: review
+summary: Review changes for bugs, regressions, and missing tests before style or polish comments.
+summary_vi: Review thay đổi tìm bug, regression, và test thiếu trước khi comment về style hoặc polish.
+triggers:
+  - review this PR
+  - review these changes
+  - look for risks before merge
+inputs:
+  - diff or changed files
+  - relevant tests or docs when needed
+outputs:
+  - severity-ranked findings
+  - open questions
+  - residual risk notes
+constraints:
+  - findings first
+  - avoid style-only comments unless they hide a real risk
+related_skills:
+  - using-skills
+  - bug-triage
+  - verification-before-completion
+  - planning

package/skills/code-review/references/checklist.md

@@ -0,0 +1,34 @@
+# Code Review Checklist
+
+Work through this list before returning findings.
+
+## Behavior
+
+- [ ] Does the change alter any existing behavior that callers depend on?
+- [ ] Are edge cases (empty input, nil/null, concurrency, off-by-one) handled?
+- [ ] Are validation rules still enforced after the change?
+
+## Regressions
+
+- [ ] Could any existing test now fail silently?
+- [ ] Were any assumptions about data shape, ordering, or timing changed?
+
+## Tests
+
+- [ ] Do the tests actually prove the intended behavior?
+- [ ] Is there a test that would catch a regression in this exact change?
+- [ ] Are any tests just checking implementation details rather than outcomes?
+
+## Safety
+
+- [ ] Are there authorization or access-control implications?
+- [ ] Are there data-loss, data-corruption, or migration risks?
+- [ ] Are there performance cliffs under realistic load?
+
+## Output format
+
+Every finding must include:
+
+- severity: blocking, major, or minor
+- location: file and line reference when available
+- impact: one sentence stating the user-visible consequence

package/skills/code-review/references/output-template.md

@@ -0,0 +1,12 @@
+## Findings
+
+1. [severity] file:line - impact and explanation
+2. [severity] file:line - impact and explanation
+
+## Open Questions
+
+- Any assumption that affects the review
+
+## Residual Risk
+
+- Brief note if no blocking issues were found

package/skills/docs-writer/SKILL.md

@@ -0,0 +1,42 @@
+# Docs Writer
+
+## Purpose
+
+Keep documentation aligned with how the system actually works.
+
+## When To Use
+
+Load this skill when writing or updating:
+
+- README files
+- onboarding docs
+- runbooks
+- API usage notes
+- project operating instructions
+
+## Workflow
+
+1. Confirm the target audience and document purpose.
+2. Verify current behavior from source, commands, or config before writing.
+3. Update only the sections that need to change.
+4. Prefer concise instructions, examples, and commands over long prose.
+5. Call out assumptions or areas that still need verification.
+
+## Output Format
+
+- target document
+- audience
+- what changed
+- source of truth used
+- assumptions or follow-ups
+
+## Red Flags
+
+- copying old docs forward without checking the current code
+- writing broad architecture claims without source verification
+- mixing user instructions with internal implementation details unnecessarily
+- leaving stale commands or paths in place
+
+## Done Criteria
+
+This skill is complete when the updated document has been verified against the actual source, all stale commands or paths have been corrected or removed, and the "Verification" field in the output names the specific files or commands that were checked.