convez.ai
SkillAutomaçãoIntermediário
hamakyo

OKF Skills

hamakyo/okf-skills

Templates OKF e Skills reutilizáveis para projetos assistidos por IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Biblioteca de Skills reutilizáveis e templates OKF (Open Knowledge Format) para projetos de engenharia com Codex e Claude Code. Fornece uma estrutura padronizada para documentar conhecimento de projeto e workflows automatizados, permitindo que agentes IA trabalhem com clareza procedural e contexto compartilhado.

Instalação

$npx convez-ai hamakyo/okf-skills

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
v0.2.0
Issues abertas
5
Contribuidores
1

Casos de uso

  • Padronizar workflows de engenharia (features, bugs, refatoração) em projetos
  • Documentar conhecimento de projeto de forma legível por humanos e agentes
  • Sincronizar instruções entre Codex e Claude Code automaticamente
  • Implementar procedimentos repetiveis com guardrails e checklists

Veredito

Projeto sólido e bem estruturado para quem precisa orchestrar agentes IA em workflows de engenharia. Recomendado para equipes que usam Codex/Claude Code e querem manter conhecimento de projeto sincronizado e legível por máquina.

README

A tradução para o português deste README ainda está na fila.

Reusable Skills and an opinionated OKF v0.2 software-project profile for Codex, Claude Code, and agent-assisted software projects.

What This Solves

Agent coding tools work best when they have both project knowledge and clear working procedures. Most repositories mix those concerns into ad hoc prompts, stale wiki pages, or long instructions that are hard to maintain.

This repository provides a small, portable reference profile:

  • OKF templates for project knowledge that humans and agents can read.
  • Skills for repeatable engineering workflows such as feature work, bug investigation, tests, refactoring, and OKF updates.
  • AGENTS.md guidance for Codex.
  • CLAUDE.md guidance for Claude Code.
  • A minimal example you can copy into your own repository.

Core Concepts

OKF

OKF, or Open Knowledge Format, is the project knowledge layer. This repository targets OKF v0.2 and adds an opinionated software-project profile for architecture, domain, data, feature, and playbook knowledge. The directory categories are profile conventions, not OKF core requirements.

OKF answers: "What is true about this project?"

Skill

A Skill is an agent-readable workflow. Each portable Skill follows the upstream Agent Skills format. Canonical Skills in this repository additionally use a consistent authoring profile with trigger conditions, required context, steps, guardrails, and a completion checklist.

Skills answer: "How should the agent do this kind of work?"

AGENTS.md

AGENTS.md is the Codex-facing instruction file. It tells Codex how to use this repository, when to read README/docs/OKF, and how to keep Skills and docs synchronized.

CLAUDE.md

CLAUDE.md is the Claude Code-facing instruction file. It mirrors the same repository rules, but is written for Claude Code users and workflows.

How The Pieces Fit

flowchart LR
    Library["Reusable source library<br/>skills/"]
    Codex["Codex project<br/>.agents/skills/"]
    Claude["Claude Code project<br/>.claude/skills/"]
    OKF["Project knowledge<br/>okf/"]
    Agents["Codex guidance<br/>AGENTS.md"]
    ClaudeMd["Claude Code guidance<br/>CLAUDE.md"]

    Library --> Codex
    Library --> Claude
    OKF --> Codex
    OKF --> Claude
    Agents --> Codex
    ClaudeMd --> Claude

Directory Structure

.
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── CHANGELOG.md
├── AGENTS.md
├── CLAUDE.md
├── docs/
│   ├── getting-started.md
│   ├── codex.md
│   ├── claude-code.md
│   ├── okf.md
│   ├── okf-software-project-profile.md
│   ├── customization.md
│   └── usage-matrix.md
├── examples/
│   ├── minimal/
│   │   ├── AGENTS.md
│   │   ├── CLAUDE.md
│   │   ├── okf/
│   │   └── skills/
│   ├── codex-project/
│   │   └── .agents/skills/
│   └── claude-code-project/
│       └── .claude/skills/
├── okf/
│   ├── index.md
│   ├── log.md
│   ├── architecture/
│   ├── domain/
│   ├── data/
│   ├── features/
│   └── playbooks/
└── skills/
    ├── implement-feature/
    ├── investigate-bug/
    ├── add-test/
    ├── refactor-safely/
    └── update-okf/

Validation and synchronization tools live under scripts/, and Skill routing fixtures live under evals/.

Quick Start

  1. Copy the minimal template into your project:

    cp -R examples/minimal/. /path/to/your-repo/
    
  2. Edit /path/to/your-repo/okf/index.md to describe your project.

  3. Add one or two project-specific OKF documents under okf/architecture/, okf/domain/, okf/data/, okf/features/, or okf/playbooks/.

  4. Ask Codex or Claude Code to use the relevant Skill:

    Use the implement-feature skill to add user profile editing.
    Read OKF first and update OKF after the implementation if behavior changes.
    

For a slower walkthrough, see Getting Started.

Using With Codex

Codex should read AGENTS.md for repository-level instructions. The top-level skills/ directory is the canonical reusable source library in this repo. In a Codex project, place auto-discovered project Skills under .agents/skills/.

Typical request:

Use the implement-feature skill to add a CSV export button.
Read README.md, docs/codex.md, and relevant OKF files before editing.

See examples/codex-project/ for the Codex auto-discovery layout.

See docs/codex.md for setup and usage details.

Using With Claude Code

Claude Code should read CLAUDE.md for repository-level instructions. The top-level skills/ directory is the canonical reusable source library in this repo. In a Claude Code project, place auto-discovered project Skills under .claude/skills/.

Typical request:

Use the investigate-bug skill.
Reproduce the issue first, summarize likely causes, then propose the smallest fix.

See examples/claude-code-project/ for the Claude Code auto-discovery layout.

See docs/claude-code.md for setup and usage details.

Skill Catalog

SkillUse whenDo not use when
implement-featureAdding a new feature or changing existing behavior.The task is only research or triage.
investigate-bugInvestigating a defect, regression, or unclear failure.The root cause and exact fix are already known.
add-testAdding or improving tests for existing behavior.The behavior is still undefined.
refactor-safelyImproving structure without behavior changes.Public APIs, schemas, or product behavior must change.
update-okfUpdating OKF after implementation or design changes.There is no user-visible, architectural, domain, data, or playbook change.

Writing OKF

Use OKF for stable project knowledge, not task instructions. A useful OKF document should usually include:

  • YAML frontmatter with at least type.
  • Optional title and description when they improve discovery.
  • Links to related OKF documents when relevant.
  • Concrete details that help an agent avoid guessing.
  • Citations or source links for claims that came from external material.
  • Optional v0.2 provenance, trust, and lifecycle metadata only when the values are known.

Example:

---
type: Feature
title: CSV Export
description: Lets users export filtered table rows as a CSV file.
tags: [export, reporting]
---

# Behavior

The export includes the same rows currently visible after filters are applied.

# Related

- Reporting overview: `okf/domain/reporting.md`

See OKF v0.2 for the upstream model and the Software Project Profile for this repository's additional conventions.

Add This To Your Own Repo

  1. Copy AGENTS.md, CLAUDE.md, and okf/ into your repository.
  2. Copy selected Skills from top-level skills/ into .agents/skills/ for Codex or .claude/skills/ for Claude Code.
  3. Rewrite okf/index.md for your project.
  4. Add project-specific knowledge under the OKF directories.
  5. Update AGENTS.md and CLAUDE.md with your test commands, coding conventions, and release rules.
  6. Keep reusable Skill source files generic enough to reuse, and keep project facts in OKF.

Customization Examples

  • Add a review-pr Skill for pull request review workflows.
  • Add okf/data/warehouse.md to document analytics tables or data contracts.
  • Add okf/playbooks/release.md for release steps.
  • Narrow refactor-safely with project-specific public API rules.
  • Add test commands to AGENTS.md and CLAUDE.md.

See docs/customization.md.

Common Usage Patterns

  • Start a feature: use implement-feature, then update-okf.
  • Debug a regression: use investigate-bug, then optionally add-test.
  • Improve coverage: use add-test with a target file, feature, or bug.
  • Clean up code: use refactor-safely and keep the diff small.
  • Refresh project knowledge: use update-okf after a meaningful implementation change.

See docs/usage-matrix.md for a compact Codex, Claude Code, and generic template comparison.

Roadmap

The next stage of OKF Skills is to move from a reusable template library toward a verifiable reference implementation for agent-assisted software maintenance. The roadmap emphasizes reliability, reproducible evaluation, and interoperability rather than adding a large number of narrowly scoped Skills.

Now — Reliability

  • Expand positive, negative, and ambiguous Skill routing fixtures and define measurable selection accuracy (#5).
  • Continue deterministic validation and synchronization checks for Skills, OKF documents, and examples.
  • Improve Codex-facing examples and document expected behavior and failure modes.

Next — Evaluation

  • Build an automated evaluation harness for Codex-facing Skills (#4).
  • Add reproducible end-to-end regression scenarios for common software-maintenance workflows (#6).
  • Separate deterministic repository checks from model-backed evaluations so failures remain diagnosable.

Later — Interoperability

  • Evaluate adapters and plugin-style packaging without replacing the portable copy-based workflow (#3).
  • Define compatibility tests for additional agentic coding environments.
  • Improve versioning and migration guidance as the OKF software-project profile evolves.

Toward v1.0

A future v1.0 should provide stable Skill conventions, reproducible evaluation coverage, a stable OKF software-project profile, documented compatibility guarantees, and clear migration rules.

Contribution

Contributions should improve reuse, clarity, or correctness without turning this repository into a project-specific prompt dump.

Before opening a pull request:

  • Read CONTRIBUTING.md.
  • Keep Skills and docs synchronized.
  • Verify links from README, AGENTS.md, and CLAUDE.md.
  • Avoid secrets, credentials, private URLs, and personal data.

Run the deterministic repository checks:

python -m pip install -r requirements-dev.txt
python -m unittest discover -s tests
python scripts/validate_markdown.py
python scripts/validate_okf.py
python scripts/validate_skills.py
python scripts/sync_examples.py --check

License

This project is released under the MIT License.

Disclaimer

This repository provides templates and operating guidance for coding agents. It does not guarantee correctness, security, legal compliance, or production readiness. Review generated changes, adapt the templates to your organization, and choose appropriate validation before public or production use.

Ver o original no GitHub

Bom para

Relacionados