indianoldturtledove/claude-skill-authoring/claude-skill-authoring

Codex OSS Maintainer Toolkit

Use this skill to turn an open-source repository into a Codex-friendly maintainer workspace.

Quick Start

./install.sh --project --target /path/to/repo --yes
./install.sh --global --yes
python3 scripts/init_skill.py issue-triage
python3 scripts/quick_validate.py .codex/skills/issue-triage

What This Skill Optimizes

• project-level AGENTS.md
• maintainer-focused Codex skills
• issue triage and bug-investigation workflows
• PR review and release-note prompts
• reusable verification commands
• cross-session dev docs for long-running tasks

Recommended Workflow

1. Audit the repository

• Identify maintainer bottlenecks: issue triage, review latency, release friction, repeated debugging.
• Map the folders that need project-specific instructions.

1. Write AGENTS.md close to the work

• Keep global instructions short.
• Add repo-specific rules, validation commands, and ownership notes.
• Prefer operational guidance over abstract philosophy.

1. Move repeatable tasks into skills or scripts

• Use scripts/init_skill.py for reusable task playbooks.
• Put durable procedures in references/.
• Put deterministic checks in templates/automation/ or project scripts.

1. Design for maintainers, not demos

• Prioritize issue triage, review, release, dependency updates, and regression checks.
• Keep verification commands next to the workflow that needs them.

1. Validate before shipping

• Run targeted checks.
• Search for stale branding or paths.
• Keep templates and examples in sync.

Maintainer Workflow Patterns

Issue Triage

• summarize the report
• classify bug vs feature vs support request
• link affected paths and owners
• propose the next maintainer action

PR Review

• inspect diff boundaries first
• check architecture, tests, rollback risk, and release notes
• produce actionable comments instead of generic praise

Debugging

• reproduce first
• inspect the failing path before editing
• test one hypothesis at a time
• verify both the fix and the absence of regressions

Release Notes

• group changes by user-facing impact
• capture migrations, flags, or rollout constraints
• link verification commands and rollback notes

Files to Read When Needed

• references/workflows.md: multi-step maintainer workflow patterns
• references/output-patterns.md: structured output formats for triage, review, and release communication
• templates/AGENTS.md: project bootstrap template
• templates/automation/README.md: helper script usage

Validation Checklist

• [ ] AGENTS.md matches the repository layout
• [ ] public docs use Codex/OpenAI terminology consistently
• [ ] skills are concise and validated
• [ ] automation scripts have explicit inputs and outputs
• [ ] examples and templates stay synchronized