Skip to content

docs: add SKILL_STYLE.md and align contribution guidelines - #14

Merged
ms-shashank merged 1 commit into
Oxcode-ai:mainfrom
h30s:feat/skill-style-guide
Aug 24, 2026
Merged

docs: add SKILL_STYLE.md and align contribution guidelines#14
ms-shashank merged 1 commit into
Oxcode-ai:mainfrom
h30s:feat/skill-style-guide

Conversation

@h30s

@h30s h30s commented Aug 24, 2026

Copy link
Copy Markdown
Member

Closes #3

What changed

  • Added SKILL_STYLE.md at the repo root defining the OxCode skill philosophy, the six core disciplinary rules with real worked before/after examples, frontmatter reference, guidelines for choosing tools and workspace, and testing standards.

  • Updated CONTRIBUTING.md to link SKILL_STYLE.md, state that PRs ignoring it will be sent back, and require before/after proof on real tasks.

  • Updated README.md to link SKILL_STYLE.md, fix plugin paths in the table, and list triage.

  • Updated template/SKILL.md so new skills scaffold directly from the style guide (defaulting to tools: chat for judgement skills and outlining disciplined rule sections).

Before and After Comparison on a Real Task

  • Task: Reviewing a diff where a method signature changed in user_service.py
    without all callers included in the changeset.

  • Before (generic/unconstrained prompt):
    "Ensure all caller functions across the codebase handle null values returned by
    this updated method." (guesses past missing context and makes claims without checking).

  • After (following SKILL_STYLE.md rules):
    "Cannot verify caller handling from this diff because user_service.py is outside
    the changeset." (refuses to claim what wasn't checked; treats missing context as a finding).

What was deliberately left out and why

  • Model-specific prompt tuning or mentioning LLM providers: OxCode routes dynamically via capability, so naming models or prompt tricks tied to a specific provider version was excluded to avoid obsolescence.

  • Prescriptive domain templates: The guide defines the discipline and standard of
    truth
    rather than attempting to catalog every possible software domain.

Tool Configuration Verification

  • Read-only review and judgement skills default to tools: chat.

  • Active skills (like test-hardening) require tools: full to execute mutations and run tests on disk rather than hallucinating outputs.

@h30s
h30s requested a review from ms-shashank August 24, 2026 13:02
@ms-shashank
ms-shashank merged commit 76d954e into Oxcode-ai:main Aug 24, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Write SKILL_STYLE.md: what makes an OxCode skill different from everyone else's

2 participants