skills-init 0.1.0

package/skills/simplify/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: simplify
+description: Use when refining recently written code, reviewing a diff for unnecessary complexity, doing cleanup passes, removing dead indirection, collapsing duplicate concepts, reducing helper bloat, or checking whether a change can be smaller without losing clarity.
+---
+
+# Simplify
+
+Use this skill to make code smaller, clearer, and easier to reason about. The
+default posture is deletion, but the goal is not the fewest lines at any cost.
+The goal is the simplest behavior-preserving shape that a future maintainer can
+trust.
+
+## Use And Near Misses
+
+Use this when:
+
+- refining code you just wrote;
+- reviewing a PR or branch for avoidable complexity;
+- doing a cleanup pass;
+- a value changes names across layers;
+- helper functions, wrapper types, or translation objects do not earn their
+  existence;
+- one concept has multiple code paths.
+
+Do not use this as the controlling skill when:
+
+- the main task is a correctness, security, or data-loss fix;
+- adding tests or safety checks increases lines but reduces risk;
+- a public API needs a small adapter for compatibility;
+- a domain concept is complex because the domain is complex;
+- readability would get worse just to make `git diff --stat` smaller.
+
+Line count is a signal, not a verdict. If simplification adds lines, explain why
+the resulting code is still simpler.
+
+## Core Questions
+
+Ask these before proposing or accepting a shape:
+
+- Can't we just use the existing value, function, or type?
+- How many names does this concept have between source and use?
+- Does this layer own a real decision, or is it just passing data through?
+- Is this state derived from existing data?
+- Is this abstraction used enough to earn a name?
+- Would deleting this make the code harder to misuse?
+
+## Simplification Moves
+
+### Prefer The Direct Version
+
+Before adding a service, helper, or abstraction, write the direct version. If the
+direct version works and stays readable, use it.
+
+```ts
+// Overbuilt: strategy object for one lookup.
+const resolver = new PriceResolver(items);
+const price = resolver.resolve(type);
+
+// Direct.
+const price = items.find((item) => item.type === type)?.price ?? null;
+```
+
+### Inline Single-Use Helpers
+
+Extract when a helper removes real duplication, names a non-obvious domain
+operation, or isolates a boundary. Inline when it only wraps a one-liner.
+
+```ts
+// Weak helper.
+function getDefaultId(items: Item[], type: string) {
+  return items.find((item) => item.type === type)?.id ?? null;
+}
+const id = getDefaultId(items, type);
+
+// Simpler.
+const id = items.find((item) => item.type === type)?.id ?? null;
+```
+
+Exception: keep a single-use helper when it creates a meaningful boundary, such
+as parsing untrusted input, encapsulating a tricky browser API, or naming a
+business rule that would otherwise be opaque.
+
+### Flatten Control Flow
+
+Prefer guard clauses and early returns over deeply nested conditionals.
+
+```ts
+function process(item: Item | null) {
+  if (!item?.isValid || item.type !== "active") {
+    return null;
+  }
+
+  return doWork(item);
+}
+```
+
+One ternary is fine. Nested ternaries are usually a rewrite.
+
+### Derive Instead Of Synchronizing
+
+If a value is computable from existing state, derive it at the point of use
+unless caching is required and justified.
+
+```ts
+// Sync liability.
+const [filteredItems, setFilteredItems] = useState<Item[]>([]);
+useEffect(() => {
+  setFilteredItems(items.filter(predicate));
+}, [items]);
+
+// Derived.
+const filteredItems = items.filter(predicate);
+```
+
+Use memoization only when there is a measured or obvious cost. Do not add cache
+invalidation problems to avoid cheap computation.
+
+### Collapse Parallel Code Paths
+
+Two functions that differ only by mode are usually one function with a clear
+option.
+
+```ts
+function getItems({
+  config,
+  includeDeprecated = false,
+}: {
+  config: Config;
+  includeDeprecated?: boolean;
+}) {
+  // shared logic
+}
+```
+
+Do not over-collapse true domain differences. If two code paths enforce
+different invariants, keep the boundary and make the distinction explicit.
+
+### Keep One Name Per Concept
+
+Name drift creates mapping code that hides bugs. Carry the same concept name
+through the stack unless crossing a real boundary or language convention.
+
+```text
+// Name drift.
+repo layer      -> workspace
+service layer   -> workspaceData
+component layer -> currentContext
+
+// One concept, one name.
+repo layer      -> workspace
+service layer   -> workspace
+component layer -> workspace
+```
+
+Acceptable boundary changes include `workspace_id` at the database layer and
+`workspaceId` in TypeScript. That is syntax convention, not semantic renaming.
+
+### Pass Objects Whole
+
+Do not destructure and rebuild objects just to rename fields. Preserve the
+original shape and add only what is new.
+
+```ts
+const enrichedProject = {
+  ...project,
+  isActive: project.settings.active,
+};
+```
+
+### Delete Translation Theater
+
+Mapping functions that only pick fields and rename them are suspicious. Keep
+them only when they enforce a real wire contract, privacy boundary, or versioned
+API.
+
+```ts
+// Usually unnecessary if no boundary is being enforced.
+function toSessionSummary(session: Session): SessionSummary {
+  return {
+    sessionId: session.id,
+    sessionStatus: session.status,
+    messageCount: session.messages.length,
+  };
+}
+```
+
+If the summary type is a public API response, the adapter may be correct. If it
+is internal plumbing, delete it and use the original object.
+
+## Anti-Patterns
+
+| Smell | Better move |
+| --- | --- |
+| Helper used in one place | Inline unless it names a real boundary. |
+| `useState` plus effect for derived data | Derive during render or memoize only when needed. |
+| Value has three names across layers | Collapse to one concept name. |
+| Same name used for different concepts | Disambiguate at the source. |
+| Function destructures and rebuilds with new keys | Spread and extend, or delete the function. |
+| Wrapper type only renames fields | Use the original type or define a real boundary DTO. |
+| Admin/app duplicate functions | One function with a clear option if invariants match. |
+| Stored field computable from existing data | Derive it unless persistence is required. |
+| New helper when an existing one does most of it | Extend existing code or use it directly. |
+| Dense reducer replacing clear code | Prefer readable multi-step code. |
+
+## Review Output
+
+When reporting simplification opportunities, keep them concrete:
+
+```markdown
+1. `<path>` / `<symbol>`
+   Current shape: <what exists now>
+   Simpler shape: <what to delete, inline, derive, or unify>
+   Why it is safe: <behavior-preserving reason or boundary note>
+   Impact: <rough line delta or removed concept>
+```
+
+For implementation, make one simplification at a time and run the narrowest
+check that proves behavior stayed intact.
+
+## Done Criteria
+
+- Removed or collapsed at least one real source of complexity, or explicitly
+  concluded that the current complexity earns its place.
+- Preserved behavior and public contracts.
+- Did not replace clear code with clever dense code.
+- Ran a focused check when code changed.
+- If line count increased, explained why the new shape is simpler.

package/skills/writing-skills/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: writing-skills
+description: Use when creating, editing, packaging, consolidating, routing, validating, or publishing agent skills under .agents/skills or a tool-specific skill directory.
+---
+
+# Writing Skills
+
+A skill is reusable operational guidance that helps a future agent recognize a
+situation and apply a proven approach. Treat skill writing like product work for
+agents: define the job, make discovery reliable, keep the path through the docs
+obvious, and verify that the skill changes behavior.
+
+## Start With Intent
+
+Before writing or editing a skill, answer these from the current task and the
+target project. Ask only for gaps that cannot be inferred.
+
+- What task should this help agents do?
+- When should it trigger? Include user phrases, symptoms, tools, paths, and
+  near-miss cases.
+- What should the agent produce or decide after reading it?
+- What 2-3 concrete tasks should it handle end to end?
+- Who is the audience: repository developer agents, user-facing runtime agents,
+  or a packaged skill bundle for many projects?
+- What existing skill, always-on guidance, script, lint, or test already covers
+  part of this?
+
+Those concrete tasks become the should-trigger prompts used during validation.
+
+## Choose The Right Home
+
+Do placement before writing content.
+
+| Home | Use for |
+| --- | --- |
+| `.agents/skills/<skill>/SKILL.md` | Project-local source of truth for reusable skills. |
+| Tool-specific links, such as `.claude/skills` | Generated symlinks or copies that point back to `.agents/skills`. |
+| `AGENTS.md` or equivalent always-on guidance | Broad rules that should apply even when no skill is invoked. |
+| `scripts/`, lint, or tests | Mechanical behavior that can be enforced automatically. |
+| Runtime workspace skill directory | User-facing skills that must be visible to a sandbox or runtime agent. |
+
+Search before adding a top-level skill:
+
+```bash
+rg --files .agents/skills | rg '/SKILL\.md$' | sort
+rg -n "keyword|tool|old-skill-name" .agents AGENTS.md .
+```
+
+Prefer adding a nested reference file under an existing skill when the new
+guidance is really a variant of an existing workflow. Keep a separate top-level
+skill when separate discovery metadata matters.
+
+## When To Create Or Keep A Skill
+
+Create or keep a skill when the guidance is reusable and requires judgment.
+
+Good fits:
+
+- non-obvious techniques;
+- repeated debugging or review workflows;
+- routing decisions;
+- tool-specific setup or failure modes;
+- API or command references that agents often misuse;
+- rubrics, quality gates, and heuristics.
+
+Poor fits:
+
+- one-off history;
+- project facts that belong in always-on guidance;
+- mechanical checks that should be linted;
+- obvious language or library docs;
+- postmortems with no reusable decision rule.
+
+If reliable automation can enforce the behavior, add or use the automation and
+make the skill point to the command.
+
+## Frontmatter
+
+Every `SKILL.md` needs:
+
+```yaml
+---
+name: lowercase-hyphen-name
+description: Use when triggering situations, symptoms, tools, paths, and user phrases apply.
+---
+```
+
+Rules:
+
+- `name` is lowercase hyphen-separated and matches the directory.
+- `description` is the main discovery surface.
+- Start descriptions with `Use when`.
+- Describe triggering conditions, not the workflow.
+- Include concrete keywords an agent or user would mention.
+- Include near-miss routing when adjacent skills could compete.
+- Keep descriptions under 1024 characters.
+- Keep XML-style angle brackets out of descriptions because descriptions are
+  often injected into structured prompts.
+
+Bad:
+
+```yaml
+description: Use when debugging - checks logs and writes a fix.
+```
+
+Good:
+
+```yaml
+description: Use when production errors, service health regressions, logs, traces, incidents, or failing monitors need investigation.
+```
+
+## Body Content
+
+Write for a future agent under time pressure.
+
+- Lead with the core principle in 1-3 sentences.
+- Put routing decisions near the top.
+- Use imperative instructions when the agent must do something.
+- Explain why a rule matters when that helps the agent generalize.
+- Prefer one excellent example over several generic examples.
+- Use tables for quick reference and comparisons.
+- Keep examples copy-pasteable when they are commands or code.
+- Avoid generic labels like `step1`, `helper2`, or `pattern3`.
+- Avoid all-caps rules unless the constraint is safety-critical or agents have
+  repeatedly rationalized around it.
+
+Do not include:
+
+- storytelling about a specific past session;
+- long transcripts or postmortems;
+- multiple language examples for the same idea;
+- full API docs that could live in `references/`;
+- instructions to use skills that are not installed with this package.
+
+## Progressive Disclosure
+
+Skills should load only the context needed for the task.
+
+- Keep `SKILL.md` as the entry point and router.
+- Move heavy material over roughly 100-300 lines into `references/`.
+- Put deterministic or repetitive work in `scripts/`.
+- Put reusable prompts, templates, and assets in `templates/` or `assets/`.
+- In the root doc, say exactly when to read each nested file.
+- Use repo-relative file paths for local references.
+
+## Cross-References
+
+Make dependency strength explicit.
+
+- Use `REQUIRED: Use <skill-name>` when the other skill must be followed.
+- Use `REQUIRED BACKGROUND: Read <skill-name>` when concepts from another skill
+  are needed.
+- Use `Optional reference: <path>` for supporting docs.
+- Avoid vague "see also" lists.
+
+## Validation
+
+Skill writing is documentation, but the output is agent behavior. Validate
+enough for the risk.
+
+### Lightweight Validation
+
+Use for small edits, reference updates, and typo-level fixes.
+
+- Search for stale references with `rg`.
+- Check local paths exist.
+- Run the package or repo skill linter.
+- Regenerate symlinks or tool copies.
+
+### Standard Validation
+
+Use for new skills, routing changes, and meaningful behavior changes.
+
+- Write 2-3 realistic prompts that should trigger the skill.
+- Write 2-3 near-miss prompts that should not trigger it.
+- Read the skill as the future agent and trace what instruction each prompt
+  should use.
+- If practical, compare with-skill behavior against without-skill behavior.
+- Fix gaps where the agent would fail to discover, over-apply, or misroute the
+  skill.
+
+### Rigorous Validation
+
+Use for high-risk discipline skills, broad consolidations, or skills that
+enforce behavior agents tend to rationalize away.
+
+- Define pressure scenarios first.
+- Observe the baseline failure if practical.
+- Write the minimal guidance that addresses the failure mode.
+- Rerun the scenario.
+- Prefer scripts or assertions for objectively checkable outputs.
+- Use human review for subjective quality.
+
+Do not turn every skill edit into an eval project. Use rigor where the cost of a
+bad skill is meaningful.
+
+## Improving Existing Skills
+
+- Preserve the original skill name unless intentionally renaming or
+  consolidating.
+- Read references and callers before changing routing.
+- Prefer deleting stale guidance over layering exceptions.
+- If feedback came from a review, fix both the specific issue and the pattern
+  that allowed it.
+- Call out non-obvious tradeoffs in release notes or PR descriptions.
+
+## Description Quality Pass
+
+Before finishing, test the description mentally against realistic prompts.
+
+- Would expected user phrasing trigger this skill?
+- Would common setup, review, or debugging workflows route correctly?
+- Would near misses avoid triggering it?
+- Does the description avoid summarizing the workflow?
+- Does it include old names or synonyms that users still say?
+
+If discovery is shaky, improve the description before expanding the body.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it fails | Fix |
+| --- | --- | --- |
+| Narrative skill | Future agents cannot reuse a one-off story. | Extract the repeatable decision, command, or pattern. |
+| Workflow hidden in description | Agent may follow the summary and skip the body. | Put triggers in description, steps in body. |
+| Missing synonyms | Users mention old tool names and the skill does not trigger. | Add old names, symptoms, and common phrasing. |
+| Link-only routing | Agents do not know when to open which doc. | Add explicit routing bullets. |
+| Overgrown root file | Agents load too much irrelevant context. | Move heavy sections to references. |
+| Excessive hard rules | Agents follow rigidly or fight the instruction. | Explain why; reserve hard rules for real constraints. |
+| Untested routing change | Skill looks clean but is undiscoverable. | Run trigger and near-miss checks. |
+
+## Checklist
+
+- [ ] Correct home: `.agents/skills`, tool-specific link, always-on guidance,
+      script, or runtime workspace skill.
+- [ ] Top-level skill is justified.
+- [ ] Name is lowercase hyphen-separated and matches the directory.
+- [ ] Frontmatter has `name` and `description`.
+- [ ] Description starts with `Use when` and contains concrete triggers.
+- [ ] Description does not summarize the workflow.
+- [ ] Description is under 1024 characters and has no XML-style tags.
+- [ ] Local references point to existing files.
+- [ ] Heavy details are moved to references, templates, assets, or scripts.
+- [ ] Examples are reusable, not narrative.
+- [ ] Validation level matches risk.