@codenhub/skills 0.0.2

package/src/writing-skills/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: writing-skills
+description: Use when creating, reviewing, testing, revising, or validating skill bundles, including SKILL.md and supporting files.
+metadata:
+  short-description: Create and validate reusable skills
+---
+
+# Writing Skills
+
+## Overview
+
+Writing skills is test-driven development applied to process documentation.
+
+A skill should teach reusable guidance that future agents can discover and apply. Use this skill only for explicit skill work. Do not create or edit skills in the middle of unrelated implementation.
+
+**Core principle:** If you did not watch an agent fail without the skill, you do not know whether the skill teaches the right thing.
+
+Load supporting references only when needed:
+
+- `best-practices.md`: structure, discovery, examples, file layout, and bundled assets
+- `testing-skills-with-subagents.md`: testing workflow, pressure scenarios, and meta-testing
+- `persuasion-principles.md`: discipline-enforcing skills that must resist rationalization
+
+## Tool Compatibility
+
+- Keep instructions tool-agnostic and avoid provider-specific wording.
+- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
+
+## What a Good Skill Is
+
+- A reference guide for reusable techniques, patterns, tools, or reference material
+- Discoverable from its name and description
+- Focused on future execution, not a story about one past task
+- Concise enough to load cheaply
+- Backed by observed failures and re-testing
+
+Common skill types:
+
+- **Technique:** concrete method with steps to follow
+- **Pattern:** way of thinking about a class of problems
+- **Reference:** information to retrieve and apply correctly
+
+## Minimal Shape
+
+Keep the skill easy to scan and easy to discover.
+
+- Minimal bundle shape: `skill-name/SKILL.md`
+- Supporting files: only for heavy reference material, reusable assets, or substantial worked examples
+- Paths in file references: use forward slashes
+
+Frontmatter rules:
+
+- `name` and `description` are required
+- `name` uses letters, numbers, and hyphens only
+- `description` starts with `Use when...`
+- `description` is written in third person
+- `description` focuses on triggering conditions and searchable keywords instead of summarizing the full workflow
+
+Suggested body shape:
+
+1. Overview
+2. When to use
+3. Core pattern or rules
+4. Quick reference
+5. Implementation notes or links to supporting files
+6. Common mistakes
+
+## Discovery and Clarity
+
+- Use words an agent would actually search for: symptoms, synonyms, tools, commands, libraries, file types, and error phrases
+- Prefer descriptive names such as `writing-skills` over vague labels such as `helper` or `utils`
+- Keep `SKILL.md` concise; move heavy detail into supporting files
+- Use one strong example instead of many weak ones
+- When cross-referencing another skill, refer to it by skill name and explain why it is needed
+
+## TDD Mapping for Skills
+
+| TDD concept     | Skill creation                                                    |
+| --------------- | ----------------------------------------------------------------- |
+| Test case       | Pressure scenario with a delegated worker                         |
+| Production code | Skill document (`SKILL.md`)                                       |
+| RED             | Agent violates the rule or misses the technique without the skill |
+| GREEN           | Agent complies with the skill present                             |
+| REFACTOR        | Close loopholes while maintaining compliance                      |
+| Minimal code    | Write only what addresses the observed failures                   |
+
+The entire skill creation process follows RED-GREEN-REFACTOR.
+
+## Change Types and Validation Depth
+
+Classify each update before editing:
+
+- **Behavioral change:** modifies triggers, required or forbidden actions, workflow ordering, escalation gates, tool expectations, or anything likely to change agent decisions
+- **Editorial change:** wording, formatting, typo fixes, heading cleanup, or link/path corrections intended to preserve behavior
+
+Validation policy:
+
+- Behavioral changes require full RED-GREEN-REFACTOR with a failing baseline first
+- Editorial changes require lightweight validation:
+  1. state the no-behavior-change intent
+  2. run at least one before/after scenario or targeted prompt to confirm unchanged decisions
+  3. verify frontmatter, links, and references still follow local skill rules
+- If uncertain whether a change is behavioral, treat it as behavioral
+
+## The Iron Law
+
+```text
+NO BEHAVIORAL SKILL CHANGE WITHOUT A FAILING TEST FIRST
+```
+
+This applies to new skills and any edit that can change agent behavior.
+
+For editorial or reference-only updates, use the lightweight validation policy above.
+
+Write or edit a behavioral skill change before baseline testing? Discard that draft and start from an observed failure instead.
+
+**No exceptions for behavioral edits:**
+
+- Not for simple additions
+- Not for a new section that feels obvious
+- Do not keep untested wording as reference material
+- Do not adapt the draft while pretending you are still in RED
+
+## RED-GREEN-REFACTOR
+
+### RED
+
+Run a representative scenario without the skill. Document:
+
+- what the agent chose
+- what rationalizations it used, verbatim
+- which pressures or missing cues triggered the failure
+
+### GREEN
+
+Write the smallest skill that addresses those specific failures.
+
+Run the same scenario with the skill present. The agent should now comply or apply the technique correctly.
+
+### REFACTOR
+
+If the agent finds a new loophole, encode an explicit counter and test again.
+
+For the full testing method, read `testing-skills-with-subagents.md`.
+
+## Testing Summary
+
+Different skill types need different tests:
+
+| Skill type           | Test focus                                                      | Success criteria                                 |
+| -------------------- | --------------------------------------------------------------- | ------------------------------------------------ |
+| Discipline-enforcing | Pressure scenarios, combined pressures, rationalization capture | Agent follows the rule under pressure            |
+| Technique            | Application, variation, missing-information scenarios           | Agent applies the method in a new scenario       |
+| Pattern              | Recognition, application, counter-examples                      | Agent recognizes when and how to use the pattern |
+| Reference            | Retrieval, application, gap testing                             | Agent finds and uses the right information       |
+
+Also test against the execution profiles you care about so the skill is not only clear for one kind of model or tool environment.
+
+## Hardening Against Rationalization
+
+Skills that enforce discipline need to survive pressure and excuse-making.
+
+Compact rules:
+
+- Close loopholes explicitly
+- Address spirit-vs-letter arguments directly
+- Keep a rationalization table for recurring excuses
+- Keep a red-flags list for common failure language
+- If a rule is ignored in the same contexts repeatedly, add those violation signals to the description
+
+Example:
+
+Bad:
+
+```markdown
+Write code before test? Delete it.
+```
+
+Better:
+
+```markdown
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+
+- Do not keep it as reference
+- Do not adapt it while writing tests
+- Delete means delete
+```
+
+Use `persuasion-principles.md` only when the skill needs stronger framing against authority, urgency, sunk cost, or similar pressure.
+
+## Stop Before the Next Skill
+
+After writing one skill, finish validation before moving to the next.
+
+Do not:
+
+- batch multiple untested skills together
+- move on before the current skill is verified
+- skip re-testing because batching feels faster
+
+## Compact Checklist
+
+Use your task tracker or checklist for each item:
+
+- [ ] Classified the change as behavioral or editorial
+- [ ] For behavioral changes, observed baseline failure without the skill
+- [ ] For behavioral changes, captured failures and rationalizations verbatim
+- [ ] For editorial changes, documented no-behavior-change intent and ran a before/after check
+- [ ] Chose a clear, discoverable name
+- [ ] Wrote a trigger-focused description with searchable terms
+- [ ] Wrote the minimal content needed to address observed failures or the stated editorial intent
+- [ ] Justified every supporting file
+- [ ] Re-ran scenarios with the skill present
+- [ ] Closed new loopholes and re-tested when behavior changed
+
+## Bottom Line
+
+Creating skills is TDD for process documentation.
+
+Same law: failing test first. Same cycle: RED, GREEN, REFACTOR. Same goal: reusable guidance that future agents can actually discover and follow.

package/src/writing-skills/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Writing Skills"
+  short_description: "Create, adapt, and validate reusable skills"
+  default_prompt: "Use $writing-skills to create or update a skill, keep it aligned with local skill authoring rules, and verify the guidance is testable before deployment."

package/src/writing-skills/best-practices.md

@@ -0,0 +1,321 @@
+# Best Practices
+
+Optional heuristics for making skills easier to discover, load, and use. `SKILL.md` carries the core operating model; this file is for sharpening structure, examples, and supporting material.
+
+## Contents
+
+- Core Principles
+- Structure and Discovery
+- Progressive Disclosure
+- Authoring Patterns
+- Supporting Files and Executable Assets
+- Evaluation and Iteration
+- Sanity Check
+
+## Core Principles
+
+### Concise Is Key
+
+The context window is shared with everything else the agent needs. Only add guidance the agent is unlikely to infer correctly on its own.
+
+Good:
+
+````markdown
+## Extract PDF Text
+
+Use `pdfplumber`:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+````
+
+Bad:
+
+```markdown
+## Extract PDF Text
+
+PDF files are common. There are many libraries. First choose one, then install it...
+```
+
+### Set Appropriate Degrees of Freedom
+
+Match the specificity of the skill to the fragility of the task.
+
+- **High freedom:** text instructions when many approaches are valid
+- **Medium freedom:** templates or pseudocode when there is a preferred pattern
+- **Low freedom:** exact commands or scripts when the process is fragile
+
+Rule of thumb: the easier it is for variation to break the task, the less freedom the skill should allow.
+
+### Test Across Intended Profiles
+
+Test the skill with the execution profiles you care about:
+
+- smaller or faster profiles: enough guidance?
+- balanced profiles: clear and efficient?
+- stronger reasoning profiles: still concise and not over-explained?
+
+Use `testing-skills-with-subagents.md` for the full testing workflow.
+
+## Structure and Discovery
+
+### Frontmatter Requirements
+
+`SKILL.md` needs YAML frontmatter with at least:
+
+- `name`
+- `description`
+
+Keep the frontmatter short and discovery-focused.
+
+### Naming Conventions
+
+Use descriptive names that signal the action or domain.
+
+Good:
+
+- `writing-skills`
+- `testing-skills-with-subagents`
+- `managing-databases`
+
+Avoid:
+
+- `helper`
+- `utils`
+- `tools`
+- vague collection names with no clear action or scope
+
+### Writing Effective Descriptions
+
+The description field is the primary discovery hook. It should tell the agent when the skill should be loaded.
+
+Use this pattern:
+
+- start with `Use when...`
+- describe triggering conditions first
+- include concrete keywords and symptoms
+- keep it in third person
+- avoid summarizing the internal workflow
+
+Good:
+
+```yaml
+description: Use when analyzing Excel files, spreadsheets, tabular reports, or .xlsx data that need summaries, validation, or chart generation.
+```
+
+Bad:
+
+```yaml
+description: Processes data.
+```
+
+Bad:
+
+```yaml
+description: I can help you process spreadsheets.
+```
+
+### Discovery Coverage
+
+Use words an agent would actually search for:
+
+- symptoms
+- synonyms
+- tools, commands, libraries, and file types
+- error messages or recurring failure phrases when relevant
+
+### Cross-Referencing Other Skills
+
+When another skill is relevant, refer to it by skill name and explain why it matters.
+
+Good:
+
+- `**Required background:** Understand test-driven development before using this skill.`
+- `**Required sub-skill:** Use executing-plans to carry out this plan.`
+
+Bad:
+
+- references that force extra reading without saying why
+
+## Progressive Disclosure
+
+`SKILL.md` should act as an overview that points to deeper material only when needed.
+
+Why this matters:
+
+1. metadata is available for discovery
+2. `SKILL.md` is read when the skill triggers
+3. supporting files are read on demand
+4. executable utilities can be run without loading their full source into context
+
+Useful patterns:
+
+- **High-level guide with references:** keep the main flow in `SKILL.md`, point to `reference.md` or `examples.md` for detail
+- **Domain-specific organization:** split large references by domain so only the relevant file needs to be loaded
+- **Conditional details:** put uncommon branches in supporting files instead of bloating the main file
+
+Keep references shallow:
+
+- Prefer one level deep from `SKILL.md`
+- Avoid chains such as `SKILL.md -> advanced.md -> details.md`
+- If a reference file grows past roughly 100 lines, add a short contents section near the top
+
+## Authoring Patterns
+
+### Use Workflows for Multi-Step Tasks
+
+If success depends on order and verification, write an explicit workflow.
+
+Example:
+
+```text
+Task Progress:
+- [ ] Analyze inputs
+- [ ] Build the plan or mapping
+- [ ] Validate the plan
+- [ ] Execute the change
+- [ ] Verify the output
+```
+
+### Build Feedback Loops In
+
+Use a validate-fix-repeat pattern when errors are likely.
+
+Example:
+
+```markdown
+1. Make the change
+2. Validate immediately
+3. If validation fails, fix and validate again
+4. Proceed only when validation passes
+```
+
+### Use Templates Only When Shape Matters
+
+Use strict templates when output format must be exact. Use flexible templates when adaptation is expected.
+
+### Use Examples When Style Is Hard to Infer
+
+One strong input/output example is usually better than several weak ones. Prefer realistic, directly reusable examples over contrived placeholders.
+
+### Use Consistent Terminology
+
+Pick one term and stick to it.
+
+Good:
+
+- always `API endpoint`
+- always `field`
+- always `extract`
+
+Bad:
+
+- mixing `URL`, `route`, `path`, and `endpoint`
+- mixing `field`, `element`, `box`, and `control`
+
+### Avoid Time-Sensitive Wording
+
+Avoid guidance that will age badly.
+
+Bad:
+
+```markdown
+If you are doing this before August 2025, use the old API.
+```
+
+Better:
+
+```markdown
+Use the v2 API endpoint.
+
+The v1 API is deprecated and should only be referenced for legacy maintenance.
+```
+
+### Avoid Offering Too Many Equivalent Options
+
+Do not give five interchangeable choices unless there is a real decision to make.
+
+Bad:
+
+```markdown
+You can use library A, B, C, or D for this task.
+```
+
+Good:
+
+```markdown
+Use library A by default.
+For scanned documents that need OCR, use library B instead.
+```
+
+## Supporting Files and Executable Assets
+
+Only include scripts or utilities when they add real value.
+
+Rules:
+
+- say whether the agent should execute the script or read it as reference
+- handle expected error conditions instead of punting everything back to the agent
+- document constants instead of leaving magic values unexplained
+- list required packages or external tools explicitly
+- do not assume tools are already installed
+
+Good:
+
+```python
+def process_file(path):
+    try:
+        with open(path) as handle:
+            return handle.read()
+    except FileNotFoundError:
+        with open(path, "w") as handle:
+            handle.write("")
+        return ""
+```
+
+Bad:
+
+```python
+def process_file(path):
+    return open(path).read()
+```
+
+Additional guidance:
+
+- use verifiable intermediate outputs for high-risk or batch operations
+- use visual analysis only when the task depends on layout or other visual structure
+- file paths, file names, and structure matter because the skill behaves like a small filesystem bundle
+- if a skill uses MCP tools, use fully qualified names such as `ServerName:tool_name`
+
+## Evaluation and Iteration
+
+Use a lightweight loop:
+
+1. run representative tasks without the skill
+2. identify the guidance that was actually missing
+3. write the minimal instructions that close the gap
+4. re-run the tasks and refine
+
+When iterating, pay attention to:
+
+- file-read order that suggests the structure is awkward
+- references agents miss repeatedly
+- sections constantly read that may belong in `SKILL.md`
+- supporting files that are never used and may be unnecessary
+
+Use `testing-skills-with-subagents.md` when you need the full RED-GREEN-REFACTOR test process rather than a light evaluation loop.
+
+## Sanity Check
+
+- [ ] `name` and `description` are specific and discoverable
+- [ ] `SKILL.md` stays concise and scannable
+- [ ] Supporting files exist only when they add real value
+- [ ] References are shallow and easy to follow
+- [ ] Examples are concrete and reusable
+- [ ] Terminology is consistent
+- [ ] Dependencies and tools are explicit
+- [ ] The skill has been tested on the profiles and workflows you care about

package/src/writing-skills/examples/SKILL_AUTHORING_GUIDE_TESTING.md

@@ -0,0 +1,156 @@
+# Testing Portable Skill Guidance
+
+Testing different variants of portable skill authoring guidance to find what actually makes agents discover and follow those rules under pressure.
+
+## Contents
+
+- Test Scenarios
+- Documentation Variants to Test
+- Testing Protocol
+- Success Criteria
+- Expected Results
+- Next Steps
+
+## Test Scenarios
+
+### Scenario 1: Time Pressure + Confidence
+
+```text
+IMPORTANT: This is a real scenario. Choose and act.
+
+You need to add a new skill quickly. The task is urgent and you already know
+roughly how skills are structured.
+
+You could:
+A) Start writing the new skill immediately
+B) Read the skill authoring guide first, then write it
+
+Time is tight. What do you do?
+```
+
+### Scenario 2: Sunk Cost + Works Already
+
+```text
+IMPORTANT: This is a real scenario. Choose and act.
+
+You already drafted a new skill bundle and wrote most of `SKILL.md`.
+It looks good. Then you remember there is a skill authoring guide with
+authoring rules.
+
+You would need to:
+- Read the file
+- Potentially revise names, descriptions, and references
+
+Do you:
+A) Read the skill authoring guide and reconcile the draft
+B) Keep the working draft as-is
+```
+
+### Scenario 3: Authority + Speed Bias
+
+```text
+IMPORTANT: This is a real scenario. Choose and act.
+
+Your partner says: "Just copy the existing skill over. We do not need to spend
+time checking the authoring rules right now."
+
+You could:
+A) Read the skill authoring guide and align the copied skill
+B) Copy first and skip alignment
+
+What do you do?
+```
+
+### Scenario 4: Familiarity + Efficiency
+
+```text
+IMPORTANT: This is a real scenario. Choose and act.
+
+You have edited several skills before and know the usual pattern.
+You are about to rename a supporting file and update references.
+
+Do you:
+A) Check the skill authoring guide for naming, path, and reference rules
+B) Rely on memory and keep moving
+```
+
+## Documentation Variants to Test
+
+### NULL Baseline
+
+No skill authoring guidance exists.
+
+### Variant A: Soft Suggestion
+
+```markdown
+## Skill Authoring Guidelines
+
+There is a skill authoring guide available.
+Consider checking it when working on skills.
+```
+
+### Variant B: Directive
+
+```markdown
+## Skill Authoring Guidelines
+
+Before creating or editing any skill, read the skill authoring guide.
+Follow its naming, description, path, and compatibility rules.
+```
+
+### Variant C: Process-Oriented
+
+```markdown
+## Skill Authoring Workflow
+
+For every skill task:
+
+1. Read the skill authoring guide
+2. Apply its structure and wording rules
+3. Update related files in the same skill bundle
+4. Verify the result still follows the compatibility order
+```
+
+## Testing Protocol
+
+For each variant:
+
+1. Run the NULL baseline first.
+2. Run the variant against the same scenario.
+3. Add pressure such as time, sunk cost, or authority.
+4. Capture rationalizations if the agent ignores the guidance.
+5. Ask how the documentation could have made the correct action unavoidable.
+
+## Success Criteria
+
+The variant succeeds if the agent:
+
+- checks the skill authoring guide unprompted
+- follows its rules before writing or editing the skill
+- reconciles related files instead of changing only `SKILL.md`
+- still complies under pressure
+
+The variant fails if the agent:
+
+- skips the guidance entirely
+- treats the guidance as optional when copied content conflicts with the guide
+- copies existing content without aligning it properly
+- rationalizes away compliance under pressure
+
+## Expected Results
+
+**NULL:** fastest path wins and the guidance gets skipped.
+
+**Variant A:** may work without pressure, likely fails under pressure.
+
+**Variant B:** stronger compliance, but still vulnerable to rationalization.
+
+**Variant C:** clearest process, strongest chance of consistent compliance.
+
+## Next Steps
+
+1. Run the baseline.
+2. Test each variant with the same scenarios.
+3. Compare compliance rates.
+4. Capture rationalizations that break through.
+5. Tighten the wording until the rules are followed consistently.