Upstream contribute
Skill event4u-app/agent-config/dist/agent-src/skills/upstream-contribute
Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package.From its SKILL.md
npx -y skills add event4u-app/agent-config --skill upstream-contributeAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 19 stars19 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.4 KB, ~2.2k tokens by cl100k_base, as published. Nobody here has run it
upstream-contribute
When to use
- A new skill was created in a project that should be shared across all projects
- A rule or skill improvement was discovered that benefits all consumers
- A bug was found in a shared skill, rule, or command
- The
learning-to-rule-or-skillskill identified something worth upstreaming - An override was created locally and should become the new default
- A project-specific skill/rule could be generalized to benefit all consumers
- The
upstream-proposalrule suggested a contribution and user agreed
Do NOT use when:
- The user has NOT given explicit consent — this is the #1 rule
- The content already exists in the shared package
- The learning is truly one-off and cannot be generalized
Goal
Contribute a learning, skill, rule, or fix from a consumer project back to the
shared agent-config package — with correct file placement, quality gates, and PR structure.
Core principles
- ⛔ Consent first — NEVER create a PR, branch, or any upstream action without explicit user approval
- Universality first — the contribution must work for ALL consumers, not just one project
- Generalize when possible — project-specific content CAN become universal with adaptation
- Evidence-based — learnings must have occurred 2+ times or be clearly generalizable
- Complete pairs — both uncondensed and condensed versions required
- Quality verified — must pass linter before PR creation
- Local benefit immediately — use override for instant project benefit while PR is pending
Package repository
The shared agent-config package lives at:
[email protected]:event4u-app/agent-config.git
GitHub: https://github.com/event4u-app/agent-config
Procedure
0. Mandatory consent gate
This step is NON-NEGOTIABLE. No exceptions.
Before ANY upstream work (branch, files, PR), ask the user:
> 🔄 This [skill/rule/guideline] could improve the shared agent-config package.
> [Brief explanation of what would be contributed and why it's valuable]
>
> 1. Yes — create an upstream PR
> 2. No — keep it project-local only
- If user picks 2 → STOP. Do not mention upstream again for this item.
- If user picks 1 → continue with the procedure below.
- If
project.upstream_repois empty in.agent-settings.yml→ ask the user to configure it first. - NEVER skip this step, even if the user previously agreed to other contributions.
1. Determine contribution type
| Type | Uncondensed path | Condensed path |
|---|---|---|
| New skill | .agent-src.uncondensed/skills/{name}/SKILL.md | .augment/skills/{name}/SKILL.md |
| New rule | .agent-src.uncondensed/rules/{name}.md | .augment/rules/{name}.md |
| New command | .agent-src.uncondensed/commands/{name}.md | .augment/commands/{name}.md |
| New guideline | .agent-src.uncondensed/guidelines/{category}/{name}.md | .augment/guidelines/{category}/{name}.md |
| Update to existing | Same path as original | Same path as original |
2. Apply locally as override (immediate benefit)
Create an override so the project benefits immediately:
agents/overrides/{type}/{name}.md
With frontmatter:
---
overrides: {type}/{name}
mode: replace # or extend
---
This step is optional if the change is low-urgency.
2b. Generalize project-specific content (if needed)
If the content is project-specific but could be made universal:
- Identify project-specific parts — domain names, local paths, project conventions
- Abstract them — replace with generic patterns, configurable values, or examples
- Show the user the diff — original vs. generalized version
- Get approval — user must confirm the generalized version is correct
Example: A project-specific "import-csv" skill → generic "file-import" skill with configurable format.
3. Prepare the upstream contribution
The agent needs access to the package repository. Ask the user:
> The improvement should go to the shared agent-config package.
> I need to create a PR in `event4u-app/agent-config`.
>
> 1. I have the package repo cloned locally — tell me the path
> 2. Clone it for me into a temp directory
> 3. I'll handle the PR manually — just give me the files
Option 1: User provides path → work directly in that repo.
Option 2: Clone into temp directory:
git clone [email protected]:event4u-app/agent-config.git /tmp/agent-config-upstream
cd /tmp/agent-config-upstream
Option 3: Output the file contents as copyable blocks for the user.
4. Create branch and files
cd {package-repo-path}
git checkout main && git pull
git checkout -b feat/skills/{name} # or fix/rules/{name}, etc.
Create both files:
- Uncondensed version →
.agent-src.uncondensed/{type}/{name}(full, verbose, human-readable) - Condensed version →
.augment/{type}/{name}(token-efficient, preserving all code blocks, headings, frontmatter, validation, gotchas)
For skills, the condensed version should be 40-60% shorter than uncondensed. For rules and commands, they are usually copied 1:1 (no condensation).
5. Ensure file quality
The files must:
- Have correct YAML frontmatter (
name,description,source: package) - NOT contain project-specific references (no domain names, local paths, FQDNs)
- Follow the skill/rule/command template structure
- Have exactly one trailing newline
6. Run quality gates (if working in the package repo)
./scripts-run src/scripts/skill_linter --all # 0 FAIL required
./scripts-run src/scripts/check_condensation # No errors for this file
./scripts-run src/scripts/condense --generate-tools # Regenerate symlinks
bash scripts/condense.sh --check # dist/agent-src/ in sync with source
bash scripts/condense.sh --check-hashes # All hashes match
If not in the package repo, note that these checks will run in CI after the PR is created.
6b. Proposal gate — MANDATORY when a proposal doc exists
If the contribution originates from a proposal under agents/proposals/
(produced by learning-to-rule-or-skill via the pipeline in
self-improvement-pipeline),
run the Stage-4 gate before opening the PR:
./agent-config proposal:check agents/proposals/{slug}.md
Hard refusal rule: if ./agent-config proposal:check exits non-zero, STOP —
do not create the branch, do not push, do not open the PR. Surface the
findings to the user, ask them to fix the proposal (add evidence,
remove TODO markers, complete required sections), then rerun.
When no proposal doc exists (small fix, typo, pure bug-fix), skip this step and document the rationale in the PR body under the Promotion Gate.
7. Commit and create PR
Branch naming: feat/skills/{name}, fix/rules/{name}, feat/commands/{name}
Commit message format:
feat(skills): add {name} skill
fix(rules): improve {name} rule — {what changed}
feat(commands): add {name} command
PR title: Same as commit message.
PR body must use the package's PR template with these gates:
- Promotion Gate — learning occurred 2+ times, improves correctness, prevents real failure
- Quality Gate — linter passes, tests pass
- Universality Gate — no project-specific assumptions, benefits all consumers
- Completeness Gate — both versions present, symlinks regenerated
8. After merge — clean up override
Once the PR is merged and the package is updated in the project:
# In the consumer project
rm agents/overrides/{type}/{name}.md
composer update event4u/agent-config # or npm update
The shared version now replaces the local override.
Output format
- Summary of what is being contributed (type, name, why)
- File contents for both uncondensed and condensed versions
- If working in the package repo: branch name, commit message, PR title
- If Option 3: copyable file blocks for the user to paste
- Reminder to clean up local override after upstream merge
Gotcha
- Agent in consumer project doesn't know the package repo URL — this skill provides it
- Agent may try to edit
.augment/in the consumer project — that's read-only (symlinked) - Agent may forget the condensed version — both are mandatory
- Agent may include project-specific references in the skill — must be universal
- The
sourcefield in frontmatter must bepackage, notproject - Agent may not have git access to the package repo — Option 3 handles this gracefully
Do NOT
- Do NOT create any upstream artifact without explicit user consent — this is the #1 rule
- Do NOT open a PR if
./agent-config proposal:checkblocks — fix the proposal first (step 6b) - Do NOT edit
.augment/in the consumer project — it's managed by the package - Do NOT submit project-specific content without generalizing it first
- Do NOT skip the condensed version — both files are mandatory
- Do NOT forget to clean up the local override after upstream merge
- Do NOT bypass quality gates — they exist for a reason
- Do NOT assume consent from a previous contribution — ask every time
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.