{
  "markdown": "<h1 align=\"center\">OKF Skills</h1>\n\n<p align=\"center\">\n  <a href=\"https://github.com/hamakyo/okf-skills/actions/workflows/markdown.yml\"><img src=\"https://github.com/hamakyo/okf-skills/actions/workflows/markdown.yml/badge.svg\" alt=\"Markdown\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"></a>\n  <a href=\"https://github.com/hamakyo/okf-skills/releases/latest\"><img src=\"https://img.shields.io/github/v/release/hamakyo/okf-skills\" alt=\"Latest Release\"></a>\n</p>\n\n<p align=\"center\">\n  English | <a href=\"README.ja.md\">日本語</a>\n</p>\n\nReusable Skills and an opinionated OKF v0.2 software-project profile for Codex, Claude Code, and agent-assisted software projects.\n\n## What This Solves\n\nAgent 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.\n\nThis repository provides a small, portable reference profile:\n\n- OKF templates for project knowledge that humans and agents can read.\n- Skills for repeatable engineering workflows such as feature work, bug investigation, tests, refactoring, and OKF updates.\n- `AGENTS.md` guidance for Codex.\n- `CLAUDE.md` guidance for Claude Code.\n- A minimal example you can copy into your own repository.\n\n## Core Concepts\n\n### OKF\n\nOKF, 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.\n\nOKF answers: \"What is true about this project?\"\n\n### Skill\n\nA 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.\n\nSkills answer: \"How should the agent do this kind of work?\"\n\n### AGENTS.md\n\n`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.\n\n### CLAUDE.md\n\n`CLAUDE.md` is the Claude Code-facing instruction file. It mirrors the same repository rules, but is written for Claude Code users and workflows.\n\n## How The Pieces Fit\n\n```mermaid\nflowchart LR\n    Library[\"Reusable source library<br/>skills/\"]\n    Codex[\"Codex project<br/>.agents/skills/\"]\n    Claude[\"Claude Code project<br/>.claude/skills/\"]\n    OKF[\"Project knowledge<br/>okf/\"]\n    Agents[\"Codex guidance<br/>AGENTS.md\"]\n    ClaudeMd[\"Claude Code guidance<br/>CLAUDE.md\"]\n\n    Library --> Codex\n    Library --> Claude\n    OKF --> Codex\n    OKF --> Claude\n    Agents --> Codex\n    ClaudeMd --> Claude\n```\n\n## Directory Structure\n\n```text\n.\n├── README.md\n├── LICENSE\n├── CONTRIBUTING.md\n├── CHANGELOG.md\n├── AGENTS.md\n├── CLAUDE.md\n├── docs/\n│   ├── getting-started.md\n│   ├── codex.md\n│   ├── claude-code.md\n│   ├── okf.md\n│   ├── okf-software-project-profile.md\n│   ├── customization.md\n│   └── usage-matrix.md\n├── examples/\n│   ├── minimal/\n│   │   ├── AGENTS.md\n│   │   ├── CLAUDE.md\n│   │   ├── okf/\n│   │   └── skills/\n│   ├── codex-project/\n│   │   └── .agents/skills/\n│   └── claude-code-project/\n│       └── .claude/skills/\n├── okf/\n│   ├── index.md\n│   ├── log.md\n│   ├── architecture/\n│   ├── domain/\n│   ├── data/\n│   ├── features/\n│   └── playbooks/\n└── skills/\n    ├── implement-feature/\n    ├── investigate-bug/\n    ├── add-test/\n    ├── refactor-safely/\n    └── update-okf/\n```\n\nValidation and synchronization tools live under `scripts/`, and Skill routing fixtures live under `evals/`.\n\n## Quick Start\n\n1. Copy the minimal template into your project:\n\n   ```sh\n   cp -R examples/minimal/. /path/to/your-repo/\n   ```\n\n2. Edit `/path/to/your-repo/okf/index.md` to describe your project.\n\n3. Add one or two project-specific OKF documents under `okf/architecture/`, `okf/domain/`, `okf/data/`, `okf/features/`, or `okf/playbooks/`.\n\n4. Ask Codex or Claude Code to use the relevant Skill:\n\n   ```text\n   Use the implement-feature skill to add user profile editing.\n   Read OKF first and update OKF after the implementation if behavior changes.\n   ```\n\nFor a slower walkthrough, see [Getting Started](docs/getting-started.md).\n\n## Using With Codex\n\nCodex should read [AGENTS.md](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/`.\n\nTypical request:\n\n```text\nUse the implement-feature skill to add a CSV export button.\nRead README.md, docs/codex.md, and relevant OKF files before editing.\n```\n\nSee `examples/codex-project/` for the Codex auto-discovery layout.\n\nSee [docs/codex.md](docs/codex.md) for setup and usage details.\n\n## Using With Claude Code\n\nClaude Code should read [CLAUDE.md](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/`.\n\nTypical request:\n\n```text\nUse the investigate-bug skill.\nReproduce the issue first, summarize likely causes, then propose the smallest fix.\n```\n\nSee `examples/claude-code-project/` for the Claude Code auto-discovery layout.\n\nSee [docs/claude-code.md](docs/claude-code.md) for setup and usage details.\n\n## Skill Catalog\n\n| Skill | Use when | Do not use when |\n| --- | --- | --- |\n| [`implement-feature`](skills/implement-feature/SKILL.md) | Adding a new feature or changing existing behavior. | The task is only research or triage. |\n| [`investigate-bug`](skills/investigate-bug/SKILL.md) | Investigating a defect, regression, or unclear failure. | The root cause and exact fix are already known. |\n| [`add-test`](skills/add-test/SKILL.md) | Adding or improving tests for existing behavior. | The behavior is still undefined. |\n| [`refactor-safely`](skills/refactor-safely/SKILL.md) | Improving structure without behavior changes. | Public APIs, schemas, or product behavior must change. |\n| [`update-okf`](skills/update-okf/SKILL.md) | Updating OKF after implementation or design changes. | There is no user-visible, architectural, domain, data, or playbook change. |\n\n## Writing OKF\n\nUse OKF for stable project knowledge, not task instructions. A useful OKF document should usually include:\n\n- YAML frontmatter with at least `type`.\n- Optional `title` and `description` when they improve discovery.\n- Links to related OKF documents when relevant.\n- Concrete details that help an agent avoid guessing.\n- Citations or source links for claims that came from external material.\n- Optional v0.2 provenance, trust, and lifecycle metadata only when the values are known.\n\nExample:\n\n```md\n---\ntype: Feature\ntitle: CSV Export\ndescription: Lets users export filtered table rows as a CSV file.\ntags: [export, reporting]\n---\n\n# Behavior\n\nThe export includes the same rows currently visible after filters are applied.\n\n# Related\n\n- Reporting overview: `okf/domain/reporting.md`\n```\n\nSee [OKF v0.2](docs/okf.md) for the upstream model and the [Software Project Profile](docs/okf-software-project-profile.md) for this repository's additional conventions.\n\n## Add This To Your Own Repo\n\n1. Copy `AGENTS.md`, `CLAUDE.md`, and `okf/` into your repository.\n2. Copy selected Skills from top-level `skills/` into `.agents/skills/` for Codex or `.claude/skills/` for Claude Code.\n3. Rewrite `okf/index.md` for your project.\n4. Add project-specific knowledge under the OKF directories.\n5. Update `AGENTS.md` and `CLAUDE.md` with your test commands, coding conventions, and release rules.\n6. Keep reusable Skill source files generic enough to reuse, and keep project facts in OKF.\n\n## Customization Examples\n\n- Add a `review-pr` Skill for pull request review workflows.\n- Add `okf/data/warehouse.md` to document analytics tables or data contracts.\n- Add `okf/playbooks/release.md` for release steps.\n- Narrow `refactor-safely` with project-specific public API rules.\n- Add test commands to `AGENTS.md` and `CLAUDE.md`.\n\nSee [docs/customization.md](docs/customization.md).\n\n## Common Usage Patterns\n\n- Start a feature: use `implement-feature`, then `update-okf`.\n- Debug a regression: use `investigate-bug`, then optionally `add-test`.\n- Improve coverage: use `add-test` with a target file, feature, or bug.\n- Clean up code: use `refactor-safely` and keep the diff small.\n- Refresh project knowledge: use `update-okf` after a meaningful implementation change.\n\nSee [docs/usage-matrix.md](docs/usage-matrix.md) for a compact Codex, Claude Code, and generic template comparison.\n\n## Contribution\n\nContributions should improve reuse, clarity, or correctness without turning this repository into a project-specific prompt dump.\n\nBefore opening a pull request:\n\n- Read [CONTRIBUTING.md](CONTRIBUTING.md).\n- Keep Skills and docs synchronized.\n- Verify links from README, `AGENTS.md`, and `CLAUDE.md`.\n- Avoid secrets, credentials, private URLs, and personal data.\n\nRun the deterministic repository checks:\n\n```sh\npython -m pip install -r requirements-dev.txt\npython -m unittest discover -s tests\npython scripts/validate_markdown.py\npython scripts/validate_okf.py\npython scripts/validate_skills.py\npython scripts/sync_examples.py --check\n```\n\n## License\n\nThis project is released under the [MIT License](LICENSE).\n\n## Disclaimer\n\nThis 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.\n",
  "bytes": 9860,
  "sha": "3ad291008bb1e03ce2b3a8661d134e63d54b83b7e83a5b4a29d946df87887225",
  "repo_slug": "hamakyo/okf-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_hamakyo_okf_skills_okf_index_md_92ebe33b/readme"
}